[SciPy-user] [SciPy-dev] Docstring standards for NumPy and SciPy

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


[Travis]
> Great.   Getting rid of back-ticks in the parameters section would  
> help
> a great deal.
>
> So does this mean
>
> :Parameters:
>    a : array
>         this is something
>    b : int
>         this is a scalar input
>
> could be how argument parameters are specified?

Indeed.  I just made & commited the change (epydoc subersion revision  
1418).

> This would be fine.
>
> I'd like an additional "field" name to describe little used parameters
> so that functions with a large number of keyword argument can still be
> well documented without cluttering the main parameters list.  Is that
> possible?

As it stands, epydoc is perfectly happy with more than one  
":Parameters:" section.. So you could list the primary parameters up  
near the top, and have a second ":Parameters:" section later on with  
the 'extra' arguments.  In fact, you might consider using the  
":Keywords:" field tag for this second section -- the only difference  
between ":Parameters:" and ":Keywords:" is that the former will  
complain if you give a description for a non-existent parameter...   
":keywords:" was originally intended for **kwargs, but epydoc is  
perfectly happy with you applying it to explicit args too...  So your  
docs would end up looking something like:

def f(x, range=10):
     """
     Summary description...

     :Parameters:
         x : int
             description of x...

     Longer description, or whatever other info you think should go  
here.

     :Keywords:
         y : int
             description of y...
     """

Of course, you don't *have* to use consolidated fields.. when you  
have a small number of parameters you could also use the slightly  
shorter:

def f(x, range=10):
     """
     Summary description...

     :param x: description of x
     :type x: int

     Longer description, or whatever other info you think should go  
here.

     :param y: description of y
     :type y: int
     """

> Where are these standard field names used?

Not sure what you mean by this question..  Docutils/rst doesn't  
define the meanings of any fields.. The fields that epydoc currently  
supports are described at <http://epydoc.sourceforge.net/fields.html>.

> I don't have a problem with back-ticks used for math.

Keep in mind, though, that using bare back-ticks for math means they  
can't also be used for cross-references.  I suspect that cross- 
references will be more common..  not just in see-also type fields,  
but also as hyperlinks in sentences such as "precision is determined  
by the `flooble` instance variable."  If you use bare back-ticks for  
math, then that would need to become "precision is determined by  
the :xref:`flooble` instance variable.  You suggest later that you  
don't expect there to be a lot of math embedded in docstrings, in  
which case the slightly more verbose `math`:\sum_i^Ni^2` doesn't seem  
like as much of a big deal.

>>> 3) doesn't understand Moin Moin tables
> I don't care so much about this.  I'm not wedded to Moin Moin's
> definition of tables except it seemed pretty minimialistic and easy  
> to use.

In that case, I see no advantage to using moinmoin table syntax.

> I think if we can agree on a suitable description of the parameters  
> list
> and on what to do about including math (I don't think there will be a
> lot of math in docstrings but there may need to be some, so we  
> ought to
> think about it) then we are there for using reST in docstrings.

Some issues still need to be worked out with formatting inline math,  
but I'm hopeful that you'll be able to use non-modified rst :)

-Edward





More information about the SciPy-user mailing list