Re: [matplotlib-devel] API Documentation usability

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

At risk of sounding defensive, all of the core developers are working mpl
on a mostly volunteer basis and only have so much bandwidth. This leads to
both thing falling through the cracks (we have close to 100 open PRs, that
is _way_ too many) and major re-factors (which every one agrees should be
done) not being done.

I fully agree the docs are less than ideal.  Some of what you suggest is
already on the radar (giving each plotting function it's own page) and a
complete overhaul of the webpage is (very slowly) in the works.
http://matplotlib.org/api/pyplot_summary.html covers some of the use-case
of the table of contents.

The reason that plotting methods appear in both `Axes` and in `pyplot` is
due to the layered design of mpl.  The actual plotting logic is implemented
as methods on the Axes object and the pyplot layer provides a MATLAB-like
state machine to make plotting convenient.  The fact that you have the same
functions in both places is a feature, not a bug ;).  We don't use
decorators for `pyplot.py` because that code pre-dates fully functional
decorators.

This part of the design, the plotting logic being _methods_ on the `Axes`
object, is why the `Axes` class is so large and I do not think can be
broken up in any sensible way (at the code level) short of abandoning it
all together and moving to modules of functions with signatures like
`fun(ax, data, style)`.  This has been discussed, but it is a HUGE change
to the architecture of the library and we are (rightly) moving slowly on
it.  MPL is a widely used mature library which means one of the most
important things we have to do is not break existing user code.

Providing human curation to the docs (a-la numpy) would be great, the main
problem is time.  The core-devs (who seem to enjoy very drudgery) are
already over whelmed, 'update the docs' is not really an exciting thing
that new contributors will jump on, and fixing the docs does require a good
deal of familiarity with the library (so you know where the docs are
wrong/misleading/missing!).

@Fabio  That bit of the already seems pretty modular, but I am not super
familiar with it.  What would you change?

If anyone wants to help with MEP10 that would be great!

Tom

On Mon Feb 16 2015 at 7:02:13 AM Fabio Zanini <fab...@tu...>
wrote:

> 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 ;-)
>
> 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
> > Mat...@li...
> > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >
>
> ------------------------------------------------------------
> ------------------
> 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
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>