[SciPy-user] Docstring standards for NumPy and SciPy

Edward Loper edloper at gradient.cis.upenn.edu
Wed Jan 17 18:41:09 CST 2007

> 1) I'm still unclear on how to include math --- please help.

The options, as I see it, are:
   a) default role=math, explicitly mark xrefs:  `x+3`  
and :xref:`get_floop()`
   b) default role=xref, explicitly mark math: :math:`x=3` and  

I'm +1 for option b, but it sounds like you lean more towards option a.

> 2) I'm still unclear on what to do about see-also.  I know we want  
> to be
> conservative in how this is used, but perhaps ought to give some help.

Two options: you can just reference other related objects as part of  
the description, and mark them as cross-references using `backticks`;  
or you can have explicit see-also fields, preferably including a  
description of *how* this object relates to that object.  So option 1:

def f(x):
     """Return the flarp of x.  For the fleep of x, use `g()`."""

Option 2:

def f(x):
     """Return the flarp of x.
     :see: `g()`, which is used to find the fleep of x."""

> 3) I don't really like using :Keywords: like I'm using it above.  I
> would prefer another special field name   that epydoc understands.
> Perhaps we can just use spacing in the :Parameters: section to convey
> the same split in the authors interpretation of the parameters.

As it turns out, epydoc *does* understand a section named :Keywords:,  
as I mentioned in my previous email.  But in the generated output,  
there will be no separation between the two groups of arguments  
(although they will be listed in the same order that you list them  
in).  So the distinction will be visible in plaintext, but not in the  
HTML/PDF output generated by epydoc.  If you *really* feel like you  
need to distinguish a second set of arguments, we could perhaps add a  
new field for this, with a new name.

> No, please let's explicitly differentiate between keywords and
> positional arguments.  [...]

They should be distinguished by the function signature.

> ... which is inaccessible if the function is written in C, for  
> example:

All C functions are strongly encouraged to begin their docstrings  
with a single-line signature.  This convention is followed by all  
standard builtin objects, functions, & methods (e.g., "help 
(list.append)"), and is understood by epydoc.  I.e., if the first  
line of a docstring is a single-line signature, epydoc will parse  
that signature and use it.  E.g., see <http://epydoc.sourceforge.net/ 

> Personally, I'd like to encourage a prose explanation with each see- 
> also
> reference. Doing so discourages the (relatively unhelpful, IMO)  
> scattershot
> lists that we've been using so far.

+1.  Or just include the references to other objects as part of the  
description, and mark them as cross-references.

> I don't know. Expressing math formulae is most important in  
> function/class
> docstrings rather than modules. See most of the docstrings for the  
> scipy.stats
> distributions, for example. And module docstrings will be seen in  
> ipython and
> similar environments, too; I'm not sure why you think they won't.  
> While I'm not
> a fan of reading raw LaTeX math expressions in plain text, it beats  
> the
> readily-available alternatives.

I tend to agree with this -- for mathematical libraries, equations  
can be a very precise & concise way to describe exactly what a  
function is doing.  On the other hand, if users can't read it, all  
the precision in the world won't help.. :)

> Excellent. May I add some, possibly troublesome examples to the  
> menagerie that I
> would like to be able to parse? I'll check out SVN epydoc tonight  
> to play with
> it myself.

Unfortunately, epydoc/rst don't currently do too well with these..

> :Parameters:
>   x : array
>   y : array
>     The x and y coordinates.

rst fails on this one -- it parses it as a paragraph containing "x :  
array y : array" followed by an illegally indented paragraph "The x  
and y coordinates", instead of parsing it as a definition list.  I  
could plausibly see the rst folks being convinced to change rst so  
that this would be parsed as a definition list, but you'd have to run  
it by them and see what they think.  As long as it's not parsed as a  
definition list by rst, it's not really possible for me to process it  

> :Parameters:
>   f : callable
>     The function to optimize.
>   *args
>     Positional arguments to apply to f().
>   **kwds
>     Keyword arguments to apply to f().

rst balks at the use of * and ** in these -- it thinks they are start  
symbols for emph and strong, respectively.  If you use `*args` and  
`**kwargs` instead, then rst parses it fine, and epydoc generates the  
output you want (it will complain because it thinks *args and  
**kwargs are unknown parameters, but that could be fixed).

> # I don't care too much about this one, but it'd be nice.
> :Parameters:
>   f : callable
>     The function to optimize.
>   *args, **kwds
>     Additional arguments to apply to f().

Assuming you put `backticks` around `*args` and `**kwargs`, rst will  
process this correctly.  Epydoc will complain that the second item is  
ill-formated, and complain about failed xrefs for `*args` and  
`**kwargs`, but will generate the correct output.  Those epydoc  
errors/warnings could be fixed.

> # I'd settle for this:
> :Parameters:
>   f : callable
>     The function to optimize.
>   *args
>   **kwds
>     Additional arguments to apply to f().

This one fails, again because it doesn't look like a definition list  
to rst.  rst parses this as a definition list with one element (f)  
followed by a paragraph "*args **kwargs" followed by an illegally  
indented paragraph "Additional arguments to apply to f()"..  So this  
one could probably be fixed iff your first example could be fixed.


More information about the SciPy-user mailing list