[SciPy-dev] Guide to NumPy/SciPy Documentation and Sphinx

[Daniel Jensen]

Pauli Virtanen <pav <at> iki.fi> writes:

> 
> On 2009-06-15, Daniel Jensen <danielsjensen1 <at> gmail.com> wrote:
> [clip]
> > I've noticed that a lot of code in SciPy is using the following format for
> > different sections:
> >
> >:Parameters:
> >
> >       func : callable func(x,*args)
> >           The objective function to be minimized.
> >
> 
> This is the old doc format which I think was used 
> non-systematically, mostly because it worked OK with epydoc. 
> Scipy contains still many docstrings written like this, Numpy 
> contains essentially none.
> 
> > whereas the Style Guideline page at
> >
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standardencourages
> > section titles like the following:
> >
> > Parameters
> > ----------
> > x : array-like
> >     array to fourier transform.
> 
> This is the new format, which supersedes the old one.
> 
> > Without some custom sphinx extension to handle the second example, Sphinx
> > spits out an "Unexpected section title" error message.  Should people
> > writing scikits or other code that may some day make it into NumPy/SciPy
> > follow one convention over the other?
> 
> The second one, I believe.
> 
> > If we should follow the first convention it may be useful to 
> > start a wiki page that explains how to get Sphinx setup 
> > correctly to process these docstrings.
> 
> Definitely a worthwhile idea. Basically, you need to do:
> 
> 	easy_install numpydoc
> 
> and then add in conf.py
> 
> 	extensions = ['numpydoc']
> 


Thanks for the quick responses, that makes a lot of sense now.  Maybe instead of
a wiki page for documentation guidelines we could copy what the Python 2.6
documentation does and just include a "Documenting SciPy - guide for
documentation authors" on the main documentation page (below the tutorial or
somewhere around there) so that everyone is on the same page.  Personally I had
a hard time finding all of the guidelines and people writing new code probably
won't all see the instructions in the documentation editor at
http://docs.scipy.org/numpy/Front%20Page/
It would be really nice to have some instructions there about including plots
and some of the custom Sphinx extensions used in NumPy/SciPy, while referring
people to the main Sphinx documentation for more general instructions.
-Daniel Jensen