[Numpy-discussion] NumPy documentation
Albert Strasheim
fullung at gmail.com
Sat Aug 5 17:11:23 CDT 2006
Hello all
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
This page:
http://www.scipy.org/SciPy2006/CodingSprints
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
library.
Maybe the example list:
http://www.scipy.org/Numpy_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
http://www.python.org/dev/peps/pep-0256/
Docstring Conventions
http://www.python.org/dev/peps/pep-0257/
Docutils Design Specification
http://www.python.org/dev/peps/pep-0258/
reStructuredText Docstring Format
http://www.python.org/dev/peps/pep-0287/
5. Documentation tools
A quick search turned up docutils:
http://docutils.sourceforge.net/
and epydoc:
http://epydoc.sourceforge.net/
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
functions.
Something else to consider is pydoc compatibility. NumPy currently breaks
pydoc:
http://projects.scipy.org/scipy/numpy/ticket/232
It also breaks epydoc 3.0a2 (maybe an epydoc bug):
http://sourceforge.net/tracker/index.php?func=detail&aid=1535178&group_id=32
455&atid=405618
Anything else? How should we proceed to improve NumPy's documentation?
Regards,
Albert
More information about the Numpy-discussion
mailing list