Looks good! I'm looking forward to doing some gallery sorting (and clean-up) in the near future.

I have a couple of very general comments. The first is that this is a definite improvement over what we have currently and I have no problem pushing something like this to the site. How would this work with subdirs, like pylab_examples/histograms?

Beyond that, I am not sure that a directory based approach is the right one. Under the "flat is better than nested' philosophy, if we break the examples into lots of dirs and subdirs, it can make it harder to find what you are looking for using file system navigation and grepping. Also, it implies a one example one concept mapping that is likely not right for many examples. One could use links to avoid this, by linking to the same example from multiple conceptual directories, but I am not sure how well this will work across platforms.

An alternative is to support some metadata tagging in the example file itself. Something simple at the top or bottom of the example like:

#_gallery_
# topic: images, colormapping

the parser would detect a comment line starting with gallery and then parse all the subsequent comment lines before a blank to extract key -> value entries for a dictionary. This would enable us to tag a single example with multiple topics, and allow us to support other metadata to enrich the gallery. Eg, we might want to have some links to the API and other docs with some simple rest markup that gets rendered, like:

#_gallery_
# topic: images, colormapping
# seealso: :func:`~matplotlib.pyplot.imshow`, :ref:`image-tutorial`, :ref:`pylab_examples-axes_demo`

I imagine the gallery would be two tiered: at the top would be any examples that are "curated" ie, already tagged with metadata. In the process of tagging them, we would clean them and comment them and implement the recommended coding practices. After all the curated examples that have topics would come "the rest" which would basically be what you have already have. All the non-curated examples, organized by directory. That way at least the stuff people see first will have been cleaned.

I will be sprinting Friday night at pydata and may try to rope some contributors in. I'd be interested in working on this if you and others want to join.

No plans for recursive subdir support. That would just make things complicated for all the reasons you stated.

The tagging idea you have is actually what I would like to implement, but I would like to try doing it within the spinx framework. I am thinking about an extension that would generate a gallery based on the tags (and maybe the examples page?) But, even further, I would like to see if a tagging approach can be used to improve the axes.py api page.

As for Friday, I will have to see how much progress I make on my current responsibilities.

What's the status here? This would be awfully nice to have.

@jdh2358 and I fleshed out a very basic sphinx tagging extension that will likely be used instead. If we want to release the next version before the SciPy conference, then we could go ahead with this idea for now and undo it later when we implement tagging. It is unlikely I will get back to this before the SciPy sprints.

This is probably a little late, but I just want to voice my support of this PR regardless of whether or not tagging is added.

Tagged examples will be a big win for users with specific goals; but for many users, the plot gallery will remain the entry point to plot examples and sections could really help users navigate the gallery. The current example directories won't be terribly useful to users, but some new directories (displayed as sections) in the gallery would help. For example:

• basic (bare-minimum code to use core plotting functions)
• advanced (plots with tweaks to make them publication-quality)
• specialty (e.g., sankey, radar, tornado)
• reference (e.g., 'show_colormaps.py', 'artist_demo.py', 'annotation_demo2.py', 'anatomy of a matplotlib plot' mentioned in improving mpl docs and accessibility for API users #524)
• separate sections for toolboxes (already exists)

These would all be top-level sections with no subsections (to address concerns about nested directories).

I think these sections would also help guide a cleanup of the examples: Initially, all the current examples would remain and be listed under their current directories. Over time, these examples could be cleaned up and then moved into one of the above categories. The old examples could then either be deleted or shoved in some dark corner for posterity. Sure, we could do this cleanup without the section headings, but with sections, it becomes obvious which examples have been updated in the gallery.

Did we still want to go ahead with this plan as a stop-gap? I have been working on a "codex-tag" sphinx extension, but haven't gotten it fully working yet. Plus we still lack the actual set of tags. There was somebody at the scipy sprints who was working on a list of tags to use, but he never emailed them to me, unfortunately.

I'd like to see this go ahead, even without tags. If you think there's a reasonable time for this before rc1 (in three weeks), please go ahead and add this to the 1.2.x milestone.

Tags aren't going to happen in time. Hurricane season sucked too much of my free time and I really got to get back to working on my dissertation.

Ok -- just for my clarification: you think this is ok to merge even without the tags?

Yes, this is the stop-gap solution until we have a proper tag solution. Essentially, the folders for the examples serves as the proxy for tags.