Goals

1. Improve the documentation content. This summer's goals:

   • A complete, professional reference guide for NumPy

     • Reference documentation (aka "docstrings") for all NumPy functions
     • Specific topic docs (slicing, broadcasting, etc.)
     • Examples ("doctests") in most/all docstrings
     • Autogeneration of HTML and PDF for the guide from the sources

   • An introductory guide to NumPy

   • Docstrings for many SciPy functions

2. Implement a framework that allows the broader community to participate in the documentation process.

   The NumPy docstrings have been extracted from the latest source code and loaded onto the documentation editor. From here, any member of the community can add, edit, or correct its content. Community technical reviewers will check each docstring for completeness, readability, and technical accuracy before merging changes into the main source tree. The editor is then updated to reflect the latest docstrings.

Volunteers and Contributors

This year's team:

• Planning, team coordination, funding: Joe Harrington
• Function docs, community coordination, technical support: Stefan van der Walt
• Documentation editor web framework: Pauli Virtanen, Emmanuelle Gouillart
• Non-function docs: Perry Greenfield
• Writing and reviewing: the NumPy community (you!)

Technologies Employed

We are looking at Sphinx, which is used to generate the Python 2.6 docs. The source code is processed as follows:

1. Extract docstrings from source code, using introspection (because some documentation is added programmatically).
2. Parse the docstrings into known sections: summary, description, parameters, examples, notes etc.
3. Re-generate the docstring using Sphinx-extended ReST.
4. Amalgamate the docstrings into a larger document, i.e. the reference guide. (If required, the docstrings can be extended in this document by adding an appropriately named .rst file to the documentation source tree).

Community Participants