My main problem with the docs is that the sourceforge html documentation is too slow for fast browsing, especially for cross-linked information. I often wished I had an htmlhelp or a local copy of the build docs.

Browsing would be much faster, and it's possible just to bookmark or add to favorites the juicy parts.tt

My last attempt to build the docs on Windows, version 98.1, I think just ended in C++ error messages. I haven't tried since.

Positive, I like the examples and gallery a lot, but sometimes I end up just browsing the examples source folder instead of the online docs.

Josef -- this is a good suggestion and an easy one to implement. I uploaded a zip file matplotlib_html.zip of the mpl web site to https://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.0. It's a large file because it contains all the images, but you can download it, unzip it, and click on index.html to browse the docs locally.

Thanks John, works nicely. and fast. (It's better to have one download than waiting 50 or 100 times for the same gallery page to load online.)

One of the big advantages of matplotlib is that it's incredibly customizable. On the flip side, this leads to a lot of object attributes, which makes introspection more difficult. One way to reduce this difficulty is to reduce the number of attributes using properties (instead of setters and getters).

Unfortunately, this will probably be difficult to implement because, IIRC, the doc generation is somehow tied to having separate setters and getters.

This is somewhat related to my setter/getter comment above.

It's a bit confusing that some functions in pyplot have mirrored axes methods but with different call signatures---e.g. plt.xlim mirrors ax.set_xlim. This comment is a little different than the above b/c it could be fixed by simply adding a property, without removing the setter/getter. (Of course, that just adds to the number of methods/attributes, which as discussed above, has its own difficulties).

In addition, there are functions in axes objects that mirror the name of pyplot functions, but don't behave the same. For example, plt.title behaves the same as ax.set_title, but there's also ax.title, which is completely different. ax.title should actually be a private attribute in this case, since you probably wouldn't want to set it directly (because it's a text object instead of simple string).

These changes would make it easier to learn the OO interface after learning the state-machine interface.

I wanted to cross-link #362, which had some criticisms, and #714 which was one approach toward something better.

Also, as a possible source of inspiration, look at some of the examples in the Grace gallery, in particular, we already have some stuff like this

and this

but pulling that into (or at least referencing from) the actual API would be very useful.

Another idea would be to provide an example where all of "standard" are mouse pick-able, and upon being selected, they spit back to you their class. (I'm just trying to think of an interactive way to solve the "I don't know how to modify an element until I know how to call it, and it's pretty non-trivial to know that a spine is called a spine, though it is documented). Not sure how feasible this last point is.

For SciPy 2012, I was planning to use mpl to create an SVG plot with
likable components called "anatomy of a matplotlib plot". This is probably
what you are thinking of?

@WeatherGod : Did you ever manage to do this? Sound great!

Further things which should be considered can be found in #362 (I closed that issue in favour of this one).

@pelson, no, my presentation wasn't accepted, so I had no time allocated to it.

Coming from Matlab, I'm happy that the examples are in a Matlab-like format, making it easy to get stuff working fast, and then slowly learn the more object-oriented approach as you use it.

It would be great if there were side-by-side examples showing how to do something the state machine matlab way and how to do the exact same thing the pythonic object-oriented way. Maybe some gallery examples, or maybe a page like http://wiki.scipy.org/NumPy_for_Matlab_Users with 3 columns: matlab, matlab-like matplotlib, pythonic matplotlib.

Hi,

This issue has been inactive for a while. What is the current state of documentation relative to the original prompt in 2011?

Better, but still in need of lots of work.

#7205 is a tracking issue for fixing the docstrings

MEP12 (http://matplotlib.org/devel/MEP/MEP12.html) is guidelines for improving the examples #7206 is tracking some of this.

I don't think keeping this open really helps anything (there are enough issues tracking docs improvements at that point...). Feel free to reopen if you disagree.