matplotlib-devel Mailing List for matplotlib

On Tue, Mar 8, 2011 at 1:18 PM, Eric Firing <ef...@ha...> wrote:
> On 03/08/2011 08:08 AM, Benjamin Root wrote:
> > 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 03/08/2011 08:08 AM, Benjamin Root wrote:
> 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.
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.
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.
Eric
>
> Thanks,
> Ben Root

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?
Thanks,
Ben Root

On 8 March 2011 09:40, Paul Hobson <pmh...@gm...> wrote:
> Is it in git or svn? I just cloned and installed from git using:
> git clone git://github.com/astraw/matplotlib.git
> cd matplotlib
> sudo python setupegg.py develop
>
> Starting ipython, and importing matplotlib, I get:
> In [2]: matplotlib.__version__
> Out[2]: '1.0.0'
>
> I thought v1.0.1 was available. Should I install from svn?
The main repository is at https://github.com/matplotlib/matplotlib you
cloned a forked copy by mistake.
> As an aside, I first tried the proceedure outlined here:
> http://matplotlib.sourceforge.net/devel/coding_guide.html#using-git
> and got a public key error.
That doc appears to be out of date. The repository move was quite recent.
Cheers,
Scott

Is it in git or svn? I just cloned and installed from git using:
git clone git://github.com/astraw/matplotlib.git
cd matplotlib
sudo python setupegg.py develop
Starting ipython, and importing matplotlib, I get:
In [2]: matplotlib.__version__
Out[2]: '1.0.0'
I thought v1.0.1 was available. Should I install from svn?
As an aside, I first tried the proceedure outlined here:
http://matplotlib.sourceforge.net/devel/coding_guide.html#using-git
and got a public key error.
Thanks,
-paul

Eric Firing <ef...@ha...> writes:
>> https://github.com/matplotlib/matplotlib/pull/17
>
> This brings up something that confuses me, together with related 
> questions, and so might be another topic for this part of the docs:
>
> 1) How is it that you were able to add commits to a branch of someone 
> else's fork?
I sent Fernando a pull request:
https://github.com/fgb/matplotlib/pull/1
He merged my commits to his branch, and his pull request was
automatically updated.
> 2) How should it be decided who merges a pull request, and when?
I think John called for not too much bureaucracy - before git we were
committing things without any review. On the other hand, with git there
is less urgency to get things into master, since if you need someone's
bugfix or feature to continue developing your own stuff, you can pull
from their branch into your own. I think we can depend on everyone's
good judgment.
If we need a guideline, my suggestion is that if someone other than the
author reviews the code and says it is good, or if no-one raises any
issues for some time, it can be merged.
If there are merge conflicts, usually the person who wrote the code is
in the best position to resolve them.
> 3) Under what circumstances, if any, should a pull request involving 
> multiple commits be collapsed into a single changeset prior to being 
> merged and pushed?
If we had a strict policy that tests must pass for every revision (which
I don't think we have had) it would make sense to squash multiple
commits into one if the intermediate commits don't pass the test
suite. Squashing is an instance of a rebase operation, so it should be
avoided for any commits on which someone may have based further work.
-- 
Jouni K. Seppänen
http://www.iki.fi/jks