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