[Numpy-discussion] Finalising documentation guidelines for NumPy
Stefan van der Walt
stefan at sun.ac.za
Tue Jul 17 07:38:08 EDT 2007
In May this year, Charles Harris posted to this mailing list
discussing some shortcomings of the current NumPy (and hence SciPy)
Since we are in the process of slowly migrating all documentation to
the new standard, it is worth revisiting the issue one last time,
before we put in any more effort.
We need a format which
- parses without errors in epydoc
- generates easily readable output and
- places sections in a pre-determined order
We also need to design a default style sheet, to aid the production of
At least the following changes are needed to the current standard:
1) In the parameters section,
var1 : type
is parsed correctly but
breaks. This can be fixed either by omitting the colon after
'var1' in the second case, or by slightly modifying epydoc's output.
2) In the SeeAlso section, variables should be surrounded by `` to
link to their relevant docstrings, i.e.
- otherfunc : relationship to thisfunc.
- `otherfunc` : relationship to thisfunc.
According to a post in the thread mentioned above, epydoc also
permutes the sections in such a way that Notes and Examples appear in
the wrong places. As far as I can tell, this is an epydoc issue,
which we should take up with Ed Loper.
If you have any information that could help us finalise the
specification, or would like to share your opinion, I'd be glad to
More information about the NumPy-Discussion