API Documentation usability - matplotlib-devel - Matplotlib
API Documentation usability Development matplotlib-devel Sebastian_Werhausen February 16, 2015, 10:42am 1 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 Fabio_Zanini February 16, 2015, 11:24am 2 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: Logit scale by iosonofabio · Pull Request #3753 · matplotlib/matplotlib · GitHub 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 ··· 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] NumPy reference — NumPy v1.26 Manual [5] Mep10 · matplotlib/matplotlib Wiki · GitHub ------------------------------------------------------------------------------ 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 [email protected] matplotlib-devel List Signup and Options