Mercurial > pylearn

comparison doc/v2_planning/coding_style.txt @ 1304:ca7e4829f6a0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged
author Olivier Delalleau <delallea@iro>
date Fri, 01 Oct 2010 14:56:54 -0400
parents a8f909502886 cc1c5720eeca
children ef0f3deead94
comparison
equal deleted inserted replaced
1303:b5673b32e8ec 1304:ca7e4829f6a0
243 How do we write docs? 243 How do we write docs?
244 244
245 Ideas (DE): 245 Ideas (DE):
246 246
247 * Most major Python projects suggest following PEP-257: 247 * Most major Python projects suggest following PEP-257:
248 http://www.python.org/dev/peps/pep-0257/, which contains conventions on 248 http://www.python.org/dev/peps/pep-0257/, which contains conventions on
249 writing docstrings (what they should contain, not the specific markup) for 249 writing docstrings (what they should contain, not the specific markup)
250 Python. These are very general conventions, however,. 250 for Python. These are very general conventions, however,.
251 251
252 * Numpy, in particular, has a very nice page on how to document things if 252 * Numpy, in particular, has a very nice page on how to document things if
253 contributing: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines 253 contributing: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
254 (it's mostly about documentation, not coding style, despite the page name). 254 (it's mostly about documentation, not coding style, despite the page
255 name).
255 256
256 * A pretty good example from numpy, with relevant comments: 257 * A pretty good example from numpy, with relevant comments:
257 http://github.com/numpy/numpy/blob/master/doc/example.py 258 http://github.com/numpy/numpy/blob/master/doc/example.py
258 259
259 * A real-life example (record arrays) from numpy: 260 * A real-life example (record arrays) from numpy:
260 http://github.com/numpy/numpy/blob/master/numpy/core/records.py 261 http://github.com/numpy/numpy/blob/master/numpy/core/records.py
261 262
262 * The recommendations are quite sane and common-sense, we should follow them. 263 * The recommendations are quite sane and common-sense, we should follow them.
263 264
264 * Make sure that what we write is compatible with tools like sphinx's autodoc 265 * numpy's way of doing things is a bit different from the way we currently
265 extension: http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc (which we 266 document Theano: they don't use param/type/rtype, for instance, but nice
266 will most probably use to generate semi-automatic pretty docs) 267 readable section titles. I personally find their approach better-looking
268 and they do have a sphinx extension that would allow us to have the same
269 style
270 (http://github.com/numpy/numpy/blob/master/doc/sphinxext/numpydoc.py).
271 The disadvantage of taking this approach is that Theano and Pylearn will
272 be documented slightly differently
273
274 * Make sure that what we write is compatible with tools like sphinx's
275 autodoc extension:
276 http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc (which
277 we will most probably use to generate semi-automatic pretty docs)
267 278
268 * Nice cheat-sheet for docutils: 279 * Nice cheat-sheet for docutils:
269 http://docutils.sourceforge.net/docs/user/rst/quickref.html 280 http://docutils.sourceforge.net/docs/user/rst/quickref.html
270 281
271 * http://docs.python.org/release/2.5.2/lib/module-doctest.html - 282 * http://docs.python.org/release/2.5.2/lib/module-doctest.html -
272 in-documentation unit-testing: we should perhaps encourage people to write 283 in-documentation unit-testing: we should perhaps encourage people to
273 such things where warranted (where there are interesting usage examples). 284 write such things where warranted (where there are interesting usage
274 notetests can automatically run those, so no configuration overhead is 285 examples). notetests can automatically run those, so no configuration
275 necessary. 286 overhead is necessary.
276 287
277 Compatibility with various Python versions 288 Compatibility with various Python versions
278 ------------------------------------------ 289 ------------------------------------------
279 290
280 * Which Python 2.x version do we want to support? 291 * Which Python 2.x version do we want to support?