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
_______________________________________________
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
