All excellent suggestions Albert. What about creating a numpy version of either the main Numeric or numarray document? I would like to see examples included in numpy of all functions. However, I think a better way to do this would be to place all examples in a separate module and create a function such as example() which would then allow something like example(arange) to spit out the example code. This would make it easier to include multiple examples for each command and to actually execute the example code, which I think is a necessary ability to make the examples testable. Examples could go in like doctests with some sort of delimiting so that they can have numbers generated and be referred to, so that you could execute, say, the 3rd example for the arange() function. Perhaps a runexample() function should be created for this or perhaps provide arguments for the example() function like example(name, number, run) The Maxima CAS package has something like this and also has an apropos() command which lists commands with similar sounding names to the argument. We could implement something similar but better by searching the examples module for similar commands, but also listing "See Also" cross references like those in the Numpy_Example_List, Gary R. Albert Strasheim wrote:

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