Hello all,
I have a free day today, so I am going through some of the documentation
and giving it a good polish. I came across one particular part that is
sorely outdated:
http://matplotlib.sourceforge.net/faq/howto_faq.html#use-show
This is in regards to the show() function and tells users that it can
only be used once in a script. By and large, this is no longer true,
but I want to make sure that I don’t give bad information here. Is
there someplace else in the docs where this information is current that
I can use for revising this section?
Not that I know of.
Because readers of the docs online may be running any of a range of mpl
versions, you will need note how show() usage and behavior have evolved.
The advantage of the old faq, outdated though it is, is that it won’t
mislead users of old mpl versions, and following its advice will still
work for users of the current version.
Good point. I hadn’t thought of that.
New behavior, or at last the target: show() starts a GUI mainloop if it
is not already running, and draws everything. If mpl is in
non-interactive mode, it then blocks until the newly opened windows have
been closed; if it is in interactive mode, it does not block. (The
macosx backend does not have a non-interactive mode.) In either case,
when things are working right, there is no restriction on multiple calls
within a script or a shell session.
Note: Michiel deHoon is working on changes to master (code and docs) so
that mpl will come up in interactive mode by default, instead of the
present non-interactive default. The code change is trivial; the larger
challenge is how to explain everything in the docs, while not confusing
users of older versions.
The whole gui situation, with all the possible combinations of
environment (ipython in its different versions, idle, etc.), mpl
backend, other packages that might be used in conjunction with mpl (e.g.
mayavi) and platform, is still unsettled. The big change was from the
0.9x series to 1.x series; some problems were sorted out between 1.0 and
1.0.1. More work in this area will be needed now and then.
All of this raises a question: can we move to clear versioning of the
online docs, as with python itself, so that a user of 0.99.x won’t be
frustrated by an example or explanation that applies only to 1.0.x? Or
can we be sufficiently careful to keep explanations of version
differences in the evolving docs? These are not mutually exclusive, and
the latter is particularly useful. For example, when using python 2.6
it is nice to be able to look at the docs and see that a feature was
introduced in that version, so it won’t be available on one’s machines
running 2.5. I think we now need to follow that practice in the mpl
docs, or at least try to do so.
I have personally had to field several questions from users of older mpl who tried the new way of creating 3d axes on their systems. Unfortunately, when I created the documentation, I completely removed all traces of the old method, forgetting that some users will have difficulty with those instructions.
Today, my goal is mostly polishing work. I will try and see if I could make some explanations more version-agnostic or to specifically point out differences in versions.
I personally see a lot of value in providing multiple versions of the docs (maybe supported - 1 releases back?).
And on the topic of the docs, if anyone has time for a bigger project:
it would be nice if the gallery could be organized in some systematic
way, so that a user could more easily use it to find a needed feature.
And as always, it would be nice to have the gallery examples cleaned up
with respect to code and comment style, and edited to remove things that
really are no longer of interest and to more clearly demonstrate features.
I can see about doing some of this tomorrow if it turns out I have another free day…
Ben Root
···
On Tue, Mar 8, 2011 at 1:18 PM, Eric Firing <efiring@…706…29…> wrote:
On 03/08/2011 08:08 AM, Benjamin Root wrote: