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

Daniel Jensen danielsjensen1@gmail....
Mon Jun 15 17:05:28 CDT 2009

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

More information about the Scipy-dev mailing list