[SciPy-dev] Docstring standards for NumPy and SciPy

[Norbert Nemec]

Nice!

I'm wondering whether the default values of optional arguments should be 
mentioned in the docstrings?


Travis Oliphant 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.
>
> 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.
>
>
> References:
>
> Use L{reference-link} for any code links (except in the see-also 
> section).  The reference-link should
> contain the full path-name (unless the function is in the same 
> name-space as this one is.
>
> Use http://  for any URL's
>
> Lists:
>
>   * item1
>     - subitem
>       + subsubitem
>   * item2
>   * item3
>
> or
>
>   1. item1
>      a. subitem
>         i.  subsubitem1
>         ii. subsubitem2
>   2. item2
>   3. item3
>
> for lists.
>
> Definitions:
>
>  descripition
>     This is my description
>     for any definitions needed.
>
> Addtional Code-blocks:
>
> {{{
> for multi-line code-blocks that are not examples to be run but should be 
> formatted as code.
> }}}
>
> Tables:
>
> Tables should be constructed as either:
>
>          +------------------------+------------+----------+
>          | Header row, column 1   | Header 2   | Header 3 |
>          +========================+============+==========+
>          | body row 1, column 1   | column 2   | column 3 |
>          +------------------------+------------+----------+
>          | body row 2             | Cells may span        |
>          +------------------------+-----------------------+
>
> or 
>
>          || Header row, column 1 || Header 2    || Header 3  ||
>          -------------------------------------------------------
>          || body row, column 1   || column 2    || column 3  ||
>          || body row 2           |||| Cells may span columns || 
>
>
> Footnotes:
>
> [1] or [CITATION3]  for Footnotes which are placed at the bottom of the 
> docstring as
>
> [1] Footnote
> [CITATION3] Additional note.
>
>
> Substitution:
>
> Use |somename|{optional text} with
>
> (the next line is placed at the bottom of the docstring in the Comments: 
> section)
> .. |somename| image::myfile.png
>
> or
>
> .. |somename| somedirective::
>  
>    {optional text}
>
> for placing restructured text directives in the main text.
>
>
> Please address comments to this proposal, very soon.  I'd like to 
> finalize it within a few days.
>
> -Travis
>
>
>  
>
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>
>