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

David Goldsmith d_l_goldsmith@yahoo....
Mon Jun 15 14:49:58 CDT 2009


--- On Mon, 6/15/09, Daniel Jensen <danielsjensen1@gmail.com> wrote:

> 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-standard
> encourages 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.

First, thanks Daniel, for calling our attention to this.

However, I'm confused - you state: "Without some custom sphinx extension to handle the _second_ example, Sphinx spits out an "Unexpected section title" error message...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."

Are you saying that presently, Sphinx (or at least the way we have it configured) is not completely compatible with _either_ of these conventions (albeit with the nature of the incompatibility differing between the two)?  Is there not a third option we could adopt which would be Sphinx-compatible "off the shelf"?

Thanks again,

DG
> 
> 
> -Daniel Jensen
> 
> 
> -----Inline Attachment Follows-----
> 
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
> 


      


More information about the Scipy-dev mailing list