[Numpy-discussion] NumPy documentation
fullung at gmail.com
Sat Aug 5 17:11:23 CDT 2006
With NumPy 1.0 mere weeks away, I'm hoping we can improve the documentation
a bit before the final release. Some things we might want to think about:
1. Documentation Sprint
mentions a possible Documentation Sprint at SciPy 2006. Does anybody know if
this is going to happen?
2. Tickets for missing functions missing docstrings
Would it be helpful to create tickets for functions that currently don't
have docstrings? If not, is there a better way we can keep track of the
state of the documentation?
3. Examples in documentation
Do we want to include examples in the docstrings? Some functions already do,
and I think think this can be quite useful when one is exploring the
Maybe the example list:
should be incorporated into the docstrings? Then we can also set up doctests
to make sure that all the examples really work.
4. Documentation format
If someone wants to submit documentation to be included, say as patches
attached to tickets, what kind of format do we want?
There's already various PEPs dealing with this topic:
Docstring Processing System Framework
Docutils Design Specification
reStructuredText Docstring Format
5. Documentation tools
A quick search turned up docutils:
Both of these support restructured text, so that looks like the way to go. I
think epydoc can handle LaTeX equations and some LaTeX support has also been
added to docutils recently. This might be useful for describing some
Something else to consider is pydoc compatibility. NumPy currently breaks
It also breaks epydoc 3.0a2 (maybe an epydoc bug):
Anything else? How should we proceed to improve NumPy's documentation?
More information about the Numpy-discussion