Features Download
From: Travis Oliphant <oliphant <at> ee.byu.edu>
Subject: Docstring standards for NumPy and SciPy
Newsgroups: gmane.comp.python.scientific.devel
Date: Wednesday 10th January 2007 14:43:28 UTC (over 10 years ago)
There was a lively discussion on the SciPy List before Christmas 
regarding establishing a standard for documentation strings for NumPy / 

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.

   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.

   Notes about the implemenation algorithm (if needed).

   This can have multiple paragraphs as can all sections.

   Additional notes if needed

   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 
      the other package).

   examples in doctest format

   This section should include anything that should not be displayed in 
a help
   or other hard-copy output.  Such things as substitution-directed 
   should go here.

Additional Information:

For paragraphs, indentation is significant and indicates indentation in 
the output.   New paragraphs are marked with blank line.


Use *italics*, **bold**, and `courier` if needed in any explanations 
(but not for variable names and doctest code or multi-line code)

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.


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


  * item1
    - subitem
      + subsubitem
  * item2
  * item3


  1. item1
     a. subitem
        i.  subsubitem1
        ii. subsubitem2
  2. item2
  3. item3

for lists.


    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 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        |


         || Header row, column 1 || Header 2    || Header 3  ||
         || body row, column 1   || column 2    || column 3  ||
         || body row 2           |||| Cells may span columns || 


[1] or [CITATION3]  for Footnotes which are placed at the bottom of the 
docstring as

[1] Footnote
[CITATION3] Additional note.


Use |somename|{optional text} with

(the next line is placed at the bottom of the docstring in the Comments: 
.. |somename| image::myfile.png


.. |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.

CD: 3ms