The documentation on how to write documentation is out of date:

http://matplotlib.org/devdocs/devel/documenting_mpl.html#documenting-matplotlib

Specifically, it should refer to our MEP10