[SciPy-dev] Guide to NumPy/SciPy Documentation and Sphinx
Pauli Virtanen
pav at iki.fi
Mon Jun 15 17:12:53 EDT 2009
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
More information about the SciPy-Dev
mailing list