[SciPy-dev] Unifying numpy, scipy, and matplotlib docstring formats

[Keir Mierle]

I'd like to help the docstring formats of numpy, scipy. and matplotlib converge
on a high-quality standard (hence the cross-posting). However, before that can
happen all maintainers from all three packages need to agree on a format. In
the interest of speeding things along, I've taken the liberty of extending [1]
the docstring format proposed by Travis on January 10th on the scipy-dev
mailing list [2]. I also volunteer to convert a non-trivial portion of the
numpy, scipy, and matplotlib docstrings. If all goes well on the consensus
front, I'll try to coordinate an IRC docstring sprint or two.

The notable differences from the format Travis posted is that I have
capitalized headers for readability; the other changes are mostly modest, or
additions to handle the more demanding requirements of matplotlib docstrings.

On the DocstringStandard page I have also put a completely re-done docstring
for the 'contour' function from matplotlib. I think it is far more readable
than the original [3]. JDH and other matplotlibheads, what do you think?
Travis, do you find my additions reasonable? Scipy maintainers, would you
consider adopting this format (especially if someone helps with the gruntwork)?

Thanks in advance,
Keir

[1] http://scipy.org/DocstringStandard
[2] http://article.gmane.org/gmane.comp.python.scientific.devel/5572
[3] http://matplotlib.sourceforge.net/matplotlib.pylab.html#-contour

p.s. This is part of my plan to kick off http://scipy.org/PyLab