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

Daniel Jensen danielsjensen1@gmail....
Mon Jun 15 14:34:38 CDT 2009


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.scipy.org/pipermail/scipy-dev/attachments/20090615/c21437a5/attachment.html 


More information about the Scipy-dev mailing list