[SciPy-dev] Docstring standards for NumPy and SciPy

[Charles R Harris]

On 1/10/07, Travis Oliphant <oliphant at ee.byu.edu> wrote:
>
>
> There was a lively discussion on the SciPy List before Christmas
> regarding establishing a standard for documentation strings for NumPy /
> SciPy.
>
> I am very interested in establishing such a standard.  A hearty thanks
> goes to William Stein for encouraging the discussion.   I hope it is
> very clear that the developers of NumPy / SciPy are quite interested in
> good documentation strings but recognize that producing them can be
> fairly tedious and un-interesting work.  This is the best explanation I
> can come up with for the relative paucity of documentation rather than
> some underlying agenda *not* to produce them.  I suspect a standard has
> not been established largely because of all the discussions taking place
> within the documentation communities of epydoc, docutils, etc.  and a
> relative unclarity on what to do about Math in docstrings.
>
> I'd like to get something done within the next few days (like placing
> the standard on a wiki and/or placing a HOWTO_DOCUMENT file in the
> distribution of NumPy).
>
> My preference is to use our own basic format for documentation with
> something that will translate the result into something that the epydoc
> package can process (like epytext or reStructuredText).  The reason, I'd
> like to use our own simple syntax, is that I'm not fully happy with
> either epytext or reStructuredText.    In general, I don't like a lot of
> line-noise and "formatting" extras.  Unfortuntately both epytext and
> reStructuredText seem to have their fair share of such things.
>
> Robert wrote some great documentation for a few functions (apparently
> following a reStructuredText format). While I liked that he did this, it
> showed me that I don't very much like all the line-noise needed for
> structured text.
>
> I've looked through a large number of documentation strings that I've
> written over the years and believe that the following format suffices.
> I would like all documentation to follow this format.
>
> This format attempts to be a combination of epytext and restructured
> text with additions for latex-math.  The purpose is to make a docstring
> readable but also allowing for some structured text directives.  At some
> point we will have a sub-routine that will translate docstrings in this
> format to pure epytext or pure restructured text.
>
> """
> 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
>
> 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.


I've been using

Required Arguments
     arg1 -- blah, blah

Keyword Arguments
    kw1 -- blah, blah

Return
    ret -- blah


Not all arguments are inputs, some are for outputs, so the word input is a
bit confusing. I note that Robert has been using word parameters instead
without distinquishing keyword arguments. Anyway, if we are going to have a
separate entry for keyword arguments, I would rather put it right after the
required arguments. I've also been single quoting variable names in the text
but am not happy about that. Should we have someway to mark variable names?

Algorithm:
>    Notes about the implemenation algorithm (if needed).
>
>    This can have multiple paragraphs as can all sections.
>
> Notes:
>    Additional notes if needed
>
> Authors:
>    name (date):  notes about what was done
>    name (date):  major documentation updates can be included here also.
>
> See also:
>    * func1 -- any notes about the relationship
>    * func2 --
>    * func3 --
>    (or this can be a comma separated list)
>    func1, func2, func3
>
>    (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).
>
> 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.
> """
>
> Additional Information:
>
> For paragraphs, indentation is significant and indicates indentation in
> the output.   New paragraphs are marked with blank line.
>
> Text-emphasis:
>
> Use *italics*, **bold**, and `courier` if needed in any explanations
> (but not for variable names and doctest code or multi-line code)
>
> Math:
>
> Use \[...\] or $...$ for math in latex format (remember to use the
> raw-format for your text string in such cases). Place it in a
> new-paragraph for displaystyle or in-line for inline style.


Why is a raw format string required? The $...$ should work inline, and for
out of line one could use $[  $] or maybe $$...$$. If the whole is going to
be translated anyway, we are free to choose our own markup.

<snip>

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20070110/5f084a41/attachment.html>