You must log in to use subscribtions.

Clear message

The NumPy/SciPy Documentation Marathon 2008– is underway! This page aims to give an overview of our goals and the roadmap for implementing them. NumPy/SciPy is a community project: we need your contributions, so don't be afraid to jump in!

How do I contribute?
If you're keen to get started right away, go straight to the documentation editor.

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

Writers

Writers should be fluent in English, must write well and grammatically, and should know the functions well enough to serve this role.

  • Stefan van der Walt
  • Perry Greenfield

Reviewers

Anyone can contribute to review, be it for technical accuracy or accessibility to a newbie. Leave your comments in the section provided underneath each docstring on the documentation editor.

Proofers

If you are a skilled, (near-) professional copy editor, we'll be doing a final, pre-release proofing of all the docs. Please let us know of your interest and experience.

Developer Zone/DocMarathon2008 (last edited 2009-05-16 14:17:52 by PauliVirtanen)