[SciPy-user] Docstring standards for NumPy and SciPy

Alan G Isaac aisaac at american.edu
Wed Jan 10 09:55:47 CST 2007

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

Alan Isaac

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

A few sentences giving an extended description.

:return:  named, list, of, outputs
   - named:     explanation
   - list:      more detail
   - of:        blah, blah.
   - outputs:   even more blah
        A little-used input not always needed.
        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


Notes about the implemenation algorithm (if needed).

This can have multiple paragraphs as can all sections.


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 
directives should go here.


More information about the SciPy-user mailing list