[SciPy-user] Docstring standards for NumPy and SciPy

Robert Kern robert.kern at gmail.com
Wed Jan 10 13:49:34 CST 2007


Travis Oliphant wrote:

> """
> one-line summary not using variable names or the function name
>
> A few sentences giving an extended description.
>
> Inputs:
>  var1      -- Explanation
>  variable2 -- Explanation
>
> Outputs:  named, list, of, outputs
>  named   -- explanation
>  list    -- more detail
>  of      -- blah, blah.
>  outputs -- even more blah

My objection to this kind of list is that it uses up a lot of valuable
horizontal space. Additionally, it either entails annoying column alignment *or*
it looks really ugly with all of the descriptions unaligned. Look at most of the
docstrings in scipy for examples. This is the Enthought standard:


Parameters
----------
var1 : type of var1 (loosely)
    Description of var1.
variable2 : type of variable2 (loosely)
    Description of variable2.
kwdarg : type of kwdarg, optional
    Description of kwdarg.


The (loose) type information is quite handy. Sometimes it is quite difficult to
tell what kind of thing the function needs from the usual description,
particularly when both scalars or arrays are flying around.

The problem with both of these forms is that they are difficult to parse into
correct lists. One issue that should be noted is that sometimes the description
of a variable is omitted because the description of the function, the variable
name, and the type information are more than enough context to tell you
everything you need to know about the parameter. The only description you can
give is just a repetition of the information that you just gave. Or two
variables are substantially similar such that you want to describe them together
only once.

""" Clip the values of an array.

Parameters
----------
arr : array
lower : number
upper : number
    The lower and upper bounds to clip the array against.
"""

This is one reason why I'm beginning to like the ReST form of this; it always
has a marker to say that this is part of a list.

""" Clip the values of an array.

:Parameters:
  - arr : array
  - lower : number
  - upper : number
    The lower and upper bounds to clip the array against.
"""

I don't think that you can write a tool that takes the ambiguous forms to the
unambiguous ones.

> Additional Inputs:    kwdarg1 -- A little-used input not always needed.
>  kwdarg2 -- Some keyword arguments can and should be given in Inputs
>             Section.  This is just for "little-used" inputs.

These should be in the Inputs section, not in a separate section.

> Algorithm:
>  Notes about the implemenation algorithm (if needed).
>
>  This can have multiple paragraphs as can all sections.

Meh. This should be in the multi-line description at the top.

> Notes:
>  Additional notes if needed

Also in the multi-line description.

> Authors:
>  name (date):  notes about what was done
>  name (date):  major documentation updates can be included here also.

I agree with Stefan that this shouldn't be in the docstring.

> See also:
>  * func1 -- any notes about the relationship
>  * func2 --
>  * func3 --
>  (or this can be a comma separated list)
>  func1, func2, func3

This kind of "See also" section is annoying to maintain, and I think that, as we
have currently been using them, they aren't very useful. The functions in
scipy.integrate shouldn't point to every other function in scipy.integrate.
That's pointless and creates a bunch of similar-looking text that gets ignored.
They should each point to scipy.integrate itself. If they have a much closer
relationship to another function (trapz() and cumtrapz() for example), then they
should include that here, but we should show great restraint when doing so. We
reduce the utility of this section by being indiscriminate.

>  (For NumPy functions, these do not need to have numpy. namespace in
> front of them)
>  (For SciPy they don't need the scipy. namespace in front of them).
>  (Use np and sp for abbreviations to numpy and scipy if you need to
> reference
>     the other package).

We shouldn't abbreviate.

> Examples:
>  examples in doctest format
>
> Comments:
>  This section should include anything that should not be displayed in a
> help
>  or other hard-copy output.  Such things as substitution-directed
> directives
>  should go here.

This should be in a comment, not a docstring. Most tools won't be aware of this
special processing that you need to apply.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco


More information about the SciPy-user mailing list