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

[Pauli Virtanen]

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']

-- 
Pauli Virtanen