# HG changeset patch
# User Dumitru Erhan <dumitru.erhan@gmail.com>
# Date 1285952166 14400
# Node ID cc1c5720eeca4e87388d1fd5b941148225c30252
# Parent  e78ced0d654016b2a15813aef94c9c275d449796
clarifications on sphinx default vs. numpydoc extension

diff -r e78ced0d6540 -r cc1c5720eeca doc/v2_planning/coding_style.txt
--- a/doc/v2_planning/coding_style.txt	Fri Oct 01 12:29:04 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Fri Oct 01 12:56:06 2010 -0400
@@ -245,34 +245,45 @@
 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,.
+     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). 
+     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 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
+     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)
+ 
+   * numpy's way of doing things is a bit different from the way we currently
+     document Theano: they don't use param/type/rtype, for instance, but nice
+     readable section titles. I personally find their approach better-looking
+     and they do have a sphinx extension that would allow us to have the same
+     style
+     (http://github.com/numpy/numpy/blob/master/doc/sphinxext/numpydoc.py).
+     The disadvantage of taking this approach is that Theano and Pylearn will
+     be documented slightly differently
+
+   * 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://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.
+     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
 ------------------------------------------