# HG changeset patch # User Dumitru Erhan # Date 1285950468 14400 # Node ID cba5a348a732a9d9847c0a40db449a741b80fdfe # Parent abc7a7e22ead7d241106c5e9696f8d60eb92f0d0 how to write docs diff -r abc7a7e22ead -r cba5a348a732 doc/v2_planning/coding_style.txt --- a/doc/v2_planning/coding_style.txt Thu Sep 30 10:18:47 2010 -0400 +++ b/doc/v2_planning/coding_style.txt Fri Oct 01 12:27:48 2010 -0400 @@ -236,7 +236,39 @@ Documentation ------------- -How do we write doc? +How do we write docs? + +Ideas (DE): + + * Most major Python projects suggest following PEP-257: +http://www.python.org/dev/peps/pep-0257/, which contains conventions on +writing docstrings (what they should contain, not the specific markup) for +Python. These are very general conventions, however,. + + * Numpy, in particular, has a very nice page on how to document things if +contributing: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines +(it's mostly about documentation, not coding style, despite the page name). + + * A pretty good example from numpy, with relevant comments: +http://github.com/numpy/numpy/blob/master/doc/example.py + + * A real-life example (record arrays) from numpy: +http://github.com/numpy/numpy/blob/master/numpy/core/records.py + + * The recommendations are quite sane and common-sense, we should follow them. + + * Make sure that what we write is compatible with tools like sphinx's autodoc +extension: http://sphinx.pocoo.org/ext/autodoc.html#module-sphinx.ext.autodoc (which we +will most probably use to generate semi-automatic pretty docs) + + * Nice cheat-sheet for docutils: + http://docutils.sourceforge.net/docs/user/rst/quickref.html + + * http://docs.python.org/release/2.5.2/lib/module-doctest.html - + in-documentation unit-testing: we should perhaps encourage people to write +such things where warranted (where there are interesting usage examples). +notetests can automatically run those, so no configuration overhead is +necessary. Compatibility with various Python versions ------------------------------------------