[SciPy-dev] Docstring standards for NumPy and SciPy

David Huard david.huard at gmail.com
Mon Jan 22 16:13:59 CST 2007


I tried to run epydoc on the example described in the wiki Jarrod created
last week, and there are some things that don't quite work.

1. The examples  section appear before the parameters and Return values,
which looks strange. I tried to fix this by adding an :example: field to
epydoc, but then the output doesn't look so good.

2. The output format of return values and parameters look different in the
pdf.

3. I can't get cross references to link to other functions in the pdf. This
is probably dumb, but I can't find the info or any example saying how to do
it.

4. Is unicode supposed to work out of the box (with the appropriate #coding
comment) ? It looks supported, but it doesn't work for me, the unicode
elements appear as the string codes in the pdf.

5. There seems to be a problem with mixing two types of parameter
definitions.
For example,

:Parameters:
  var1 : type
    Explanation
  var2 : type
    Explanation

:OtherParameters:
  - `r`: Compact description

Returns almost the right thing, but the indentation is not quite right and
the type for var2 is put on a new line.

Also, it may be good practice to let the first line of the docstring be the
function signature, as function wrappers may just define *args, **kwds,
which is not very informative. This would have no impact on the pdf, because
epydoc replaces the uninformative function signature by the one given in
this first line.


David


2007/1/22, Robert Kern <robert.kern at gmail.com>:
>
> Norbert Nemec wrote:
> > Nice!
> >
> > I'm wondering whether the default values of optional arguments should be
> > mentioned in the docstrings?
>
> I've suggested "Don't." as they can be found from the signature. The
> signature
> should always be available from regular Python functions and should be
> included
> in the docstring for extension functions. Anything that requires more
> explanation than that can be described in prose in the parameter's
> description.
>
> --
> 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
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.scipy.org/pipermail/scipy-dev/attachments/20070122/18077862/attachment.html 


More information about the Scipy-dev mailing list