API Documentation usability

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

Dear Sebastian,

I agree with your impression. I made a pull request for some axis
functionality (logit scales) and the PR got lost. I am convinced that:

1. working on things like axes, ticker, scales, locators would be a lot
easier with a little refactoring of the code

2. with a more modular codebase, my PR would be accepted by now, instead
of living in limbo waiting to be forgotten.

So I am in general in favour of your proposal.

See also: https://github.com/matplotlib/matplotlib/pull/3753

Cheers,
Fabio

PS: if Thomas or anybody else is still willing to accept my PR itself,
I'd be in favour too. But please do not make me rebase another 3 times
before that :wink:

ยทยทยท

On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:

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

------------------------------------------------------------------------------
Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
from Actuate! Instantly Supercharge Your Business Reports and Dashboards
with Interactivity, Sharing, Native Excel Exports, App Integration & more
Get technology previously reserved for billion-dollar corporations, FREE
http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel