Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Tony Yu <ts...@gm...>]

Hi Michael,

Thanks for reading the MEP! Responses below:

On Tue, Dec 11, 2012 at 1:10 PM, Michael Droettboom <md...@st...> wrote:

>  On 12/10/2012 05:18 PM, Tony Yu wrote:
>
> <snip>

> MEP 12 outlines the reorganization of the example gallery and subsequent
> clean up of the examples:
>
>
>      https://github.com/matplotlib/matplotlib/wiki/MEP12
>
>  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.
>

I noted that old examples could either be kept in a dark corner, or
deleted. I'm actually strongly in favor of deleting, especially since the
website is versioned (nice---I didn't know this). I was afraid some people
would be resistant to deleting, but I'm happy to hear that you prefer it.
I'll make this preference clearer in the MEP.

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

I agree that "plotting" is too general. My only hesitation with the finer
classification of plots is that it's really hard to come up with categories
that work; my current suggestions in the MEP aren't really ideal.
Nevertheless, I'm sure we can all put our heads together to come up with
categories that make sense...



> 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.
>

Agreed.

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 definitely agree.

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 was hesitant to add this initially. I agree it's sometimes a good idea to
have multiple figures. I'd still like to have this as a suggestion---I'll
try to make that a little clearer in the MEP.


>  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.
>

Sounds good.

Best,
-Tony