[SciPy-dev] Guide to NumPy/SciPy Documentation and Sphinx
Mon Jun 15 16:12:53 CDT 2009
On 2009-06-15, Daniel Jensen <firstname.lastname@example.org> wrote:
> I've noticed that a lot of code in SciPy is using the following format for
> different sections:
> 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:
> 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:
and then add in conf.py
extensions = ['numpydoc']
More information about the Scipy-dev