[Numpy-discussion] NumPy documentation

[Albert Strasheim]

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