[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