[matplotlib-devel] API Documentation usability

[Sebastian W. <swe...@gm...>]

I'm a newcomer to the MPL code, and getting an overview is not easy.
Especially the API part of the documentation [1] has a lot of room for
improvement. The functionality of the MPL sources seems to be
scattered quite loosely among the sources and their structure is
directly mirrored in the doc. Some observations:

1. Many functions like quiver() or bar() are in multiple places
(pyplot and axes)
2. Some entries (like axes) are enormous, making them very hard to use
to get an overview
3. The API start page is just a lose list of classes, without
indication what's inside

Ideally I feel like the code itself should be organized in smaller
chunks, but that's probably unrealistic. A quick improvement for 2.
could be to add a "table of contents" at the top of every class
documentation. For axes, that could work like [2] and look like [3].
Thoughts? I wanted to test the waters before making pull requests.

Another way could be to organize the documentation not by classes, but
by functionality. The Numpy docs [4] seem much more usable in that
regard. That'll be less automatic of course but could help with
observation 3.

I've also found the Mep10 [5] on the Wiki with many good ideas, but
not sure if that lead somewhere.

Sebastian


[1] http://matplotlib.org/api/index.html
[2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1
[3] http://i.imgur.com/d1uTjfS.png
[4] http://docs.scipy.org/doc/numpy/reference/
[5] https://github.com/matplotlib/matplotlib/wiki/Mep10