You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
improving mpl docs and accessibility for API users #524
There was a recent discussion on the numpy mailing list about how to improve the accessibility of the docs and the gallery, particularly for API users who find the pylpot state-machine annoying. Add your suggestions and gripes here.
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.
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?
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.
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.
Activity
josef-pkt commentedon Oct 13, 2011
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.
jdh2358 commentedon Oct 13, 2011
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.
josef-pkt commentedon Oct 14, 2011
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.)
tonysyu commentedon Oct 14, 2011
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.
tonysyu commentedon Oct 14, 2011
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.
ivanov commentedon Jun 8, 2012
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
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.
WeatherGod commentedon Jun 9, 2012
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?
pelson commentedon Oct 18, 2012
@WeatherGod : Did you ever manage to do this? Sound great!
pelson commentedon Oct 18, 2012
Further things which should be considered can be found in #362 (I closed that issue in favour of this one).
WeatherGod commentedon Oct 22, 2012
@pelson, no, my presentation wasn't accepted, so I had no time allocated to it.
endolith commentedon Apr 11, 2014
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.
petehuang commentedon Dec 28, 2016
Hi,
This issue has been inactive for a while. What is the current state of documentation relative to the original prompt in 2011?
tacaswell commentedon Dec 29, 2016
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.
anntzer commentedon Jan 11, 2018
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.