NumPy Documentation Marathon

A SciPy Community Effort

Part 1:	Stéfan van der Walt, University of Stellenbosch, South Africa
Interlude:	Michael Droettboom on Matplotlib docs
Part 2:	Joe Harrington, University of Central Florida, U.S.A.

Introduction

• First ever NumPy documentation drive
  • Funded by the University of Central Florida
  • Under the administration of Joe Harrington

• Focus not only on writing docs, but on creating a framework which allows community participation
  • Joe will give a project overview and motivation
• My job to tell you more about the technical side of things:
  • The infrastructure we have built
  • The contribution/review process
  • What we have produced

Web-based editor

• Idea started to form at the NiPy sprint in Paris
• First work done by Emmanuelle Gouillart
• Soon after, Pauli Virtanen announced his system on the mailing list
  • At this point, we joined efforts. Soon after, a MoinMoin modification was produced that could take care of basic needs (rendering docstrings from ReStructuredText, generating NumPy patches).
• Discovered that we had needs that MoinMoin could not satisfy
  • Fine grained access control
  • Work-flow
  • Statistics
  • Comments system
  • And... (many more ideas)
• Pauli Virtanen did the majority of work on this part of the project (Demo web-app)

Documentation Standard

• Before we started to document, it was important that we came to an agreement as to the exact format of the docstrings
• The NumPy docstring format was more-or-less standardised already, so we opted to parse it, rather than adopt the markup of a specific tool
• See docstring standard

Workflow

• Import docstrings into editor via intermediate XML

• Review became possible with the web-app
• See review flow-chart
• Did not proceed beyond reviewing this year

• Merge with SVN NumPy
• Handle conflicts
• Generate selected patches

Progress Made

• Started with a short-list of 50 functions for Joe's classes
• After those were done, we added another 280 or so functions to the targeted list.
• About 20% of those have been completely documented.
• Another 33% are in progress
• 30 editors signed up, excluding myself, Joe and Pauli (I owe Joe an ice-cream).
• Bug reports and fixed in NumPy
• numpy.doc infra-structure
• Patch to Sphinx to fix searching
• Reference guide (see next slide)

Reference Guide

• Built using Sphinx
• NumPy docstrings are extracted and parsed (NumpyDocString)
• This object knows how to regenerated itself using Sphinx-compatible markup (amongst others)
  • Integrated into Sphinx using plugin
• Show reference guide

Conclusion

• Thanks to everybody who helped out!
• The documentation marathon has set the wheel rolling, but there is a lot of work left to do.
• Get involved!
  • Editing
  • Reviewing
  • Further development of web editor for SciPy