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

[Daniel Jensen]

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.

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.

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

-Daniel Jensen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090615/c21437a5/attachment.html>