On 12/10/2012 05:18 PM, Tony Yu wrote:
Hi all,

I'm not sure if non-core-developers are allowed to post MEPs, but I just did ;).

It's a big tent.  Come on in!  BTW -- if you want to have access to the big green merge button, let me know.  You've certainly been working on matplotlib long enough, to say the least.  :)

MEP 12 outlines the reorganization of the example gallery and subsequent clean up of the examples:


In my opinion, there are two open questions in the MEP:

    * Section names (may seem trivial to some, but I think it's really important)
    * Guidelines for cleaning up examples

Some thoughts:

You suggest keeping the old examples around in some dark corner.  Is there some advantage you envision for doing this?  I'd just as soon remove them.  Note that the documentation on the website is now versioned, so the examples that shipped with 1.2.0 will remain live and unchanged indefinitely.  If a user wants the older gallery it should just be there under matplotlib.org/1.2.

As for the categories/structure, I think I prefer your "suggested alternative" -- to have narrowly defined categories rather than a big "plotting" directory.

For "cleanup guidelines", perhaps it is worth mentioning that some of the examples are really unit tests -- they just exercise some esoteric feature that's only of interest to developers.  These should be converted into unit tests from the framework and probably deleted altogether as gallery examples.

Maybe we should also add that examples should be renamed when appropriate: there are things like "image_demo.py" and "image_demo2.py".  The "2" doesn't really help to describe what's in there.

I'm not sure I agree with "one figure per example" as a goal -- it is sometimes nice to have a number of features demonstrated by a single example file, and cramming them all into multiple axes isn't always the best approach.  I think we can take that on a case-by-case basis.

I agree with Phil that we might as well just iterate this on master.  I would envision one or two PRs to get the general infrastructure in place, and then lots of PRs from multiple authors as we work on whipping the examples into shape.

Note that I haven't started doing this yet, but I will probably start periodically posting built documentation of master on the website -- that should make it easy for anyone to preview the new gallery and provide feedback as we work.