[SciPy-user] Docstring standards for NumPy and SciPy
aisaac at american.edu
Wed Jan 10 12:54:38 CST 2007
I am not trying to "argue" for reST+epydoc, but rather to
add my perspective on some of the arguments pro and con.
Here are some issues that have been raised.
I will copy Ed Loper, in case he wants to comment.
Must items (e.g., parameters) in a consolidated field be
marked as interpreted text (with back ticks).
Yes. It does seem redundant, so I will ask why.
Would it not be nice to have :Inputs: and :Outputs:
consolidated fields as synonyms for :Parameters:
Yes! Perhaps Ed Loper would be willing to add this.
Can new fields be added?
(In addition, the author has added fields in response
Is Epydoc easily customizable?
In what ways? It is easy to add new fields
(see above), but I do not know about new
Can you put type and precision right after the variable
in a :Parameters: list?
(Yes; see the very last example)
Is table support adequate in reST?
So *maybe* not, although I am not currently imagining
a table that will be used in documentation that cannot
be accommodated (are elements in multiple cells really
needed?). And of course, any plain text table can be
retained as a literal block.
Is the use of directives "cluttered"?
Not in my opinion. For example::
f(x) = x^2
does not seem more cluttered to me than::
f(x) = x^2
However it would be nice to keep the default role for
math, so we could inline `f(x)=x^2` rather than
:latex-math:`f(x)=x^2`. It may be worth asking whether
epydoc developers would be willing to pass $f(x)=x^2$
Are there date and version fields?
There are, called 'since' and 'version'.
Why use underlining to define sections?
So that they are really sections.
The indented examples will display fine
but will not give access to sectioning controls.
More information about the SciPy-user