# HG changeset patch
# User Dumitru Erhan <dumitru.erhan@gmail.com>
# Date 1285950544 14400
# Node ID e78ced0d654016b2a15813aef94c9c275d449796
# Parent  cba5a348a732a9d9847c0a40db449a741b80fdfe# Parent  24890ca1d96bc044cc16da30a28f97b86ee28b37
merge

diff -r 24890ca1d96b -r e78ced0d6540 doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Fri Oct 01 12:19:55 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Oct 01 12:29:04 2010 -0400
@@ -240,7 +240,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
 ------------------------------------------