[Numpy-discussion] NumPy documentation

[Gary Ruben]

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