[SciPy-user] Docstring standards for NumPy and SciPy

[Alan G Isaac]

On Wed, 10 Jan 2007, Travis Oliphant apparently wrote: 
> I'm strongly against line-noise in the docstrings. 

Although I am a user not a developer, I have some experience 
with reStructuredText and epydoc, and I wonder if they are 
as "noisy" as you fear.  In general I think it gives 
a very clean and readable look, and links are particularly 
clean.  A big advantage is that the tools for processing 
exist and are very good.  The idea that reST introduces 
a lot of "noise" is contrary to my limited experience.  Do 
I recall that Fernando Perez was exploring using the 
latex-math support in documentation: if so, maybe he can 
report on the experience.  (I have used it in documents, 
where it works great, but not in documentation.)

I believe your example becomes something like the below 
(doing this quickly).  There is also additional 
functionality available.  For example, you can accumulate 
a change log, which is nice!

The main thing that seems to be missing in the example is 
a :notes: field that could hold multiple notes and perhaps 
somthing equivalent for :see:.

fwiw,
Alan Isaac


"""
one-line summary not using variable names or the function name

A few sentences giving an extended description.

:Parameters:
   `var1`
        Explanation
   `variable2`
        Explanation
:return:  named, list, of, outputs
   - named:     explanation
   - list:      more detail
   - of:        blah, blah.
   - outputs:   even more blah
:Keywords:
   `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.
:note: Additional notes if needed
:note: More additional notes if needed
:author: name (date):  notes about what was done
:author: name (date):  major documentation updates can be included here also.
:see: func1 -- any notes about the relationship
:see: func2 --
:see: func3 --
:see: func4, func5, func6

Algorithm
---------

Notes about the implemenation algorithm (if needed).

This can have multiple paragraphs as can all sections.


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.

"""