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