.. author:: Tony S Yu

Discussion

None so far.

Reorganizing the matplotlib plot gallery would greatly simplify navigation of the gallery. In addition, examples should be cleaned-up and simplified for clarity.

The matplotlib gallery was recently setup to split examples up into sections. As discussed in that PR [1], the current example sections (api, pylab_examples) aren't terribly useful to users: New sections in the gallery would help users find relevant examples.

These sections would also 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 moved into one of the new sections. The old examples could then either be deleted or shoved in some dark corner for posterity.

This process allows users to easily identify examples that need to be cleaned up; i.e. anything in the api and pylab_examples directories.

1. Create new gallery sections.
2. Clean up examples and move them to the new gallery sections (over the course of many PRs and with the help of many users/developers).

The naming of sections is critical and will guide the clean-up effort. The following is a list of proposed sections:

• plotting (minimal code to use core plotting functions---i.e., all first-class plotting functions in the pyplot namespace)
• text and annotation
• spines, subplots, and axes
• specialty (e.g., sankey, radar, tornado)
• showcase (plots with tweaks to make them publication-quality)
• reference (e.g., 'show_colormaps.py', 'artist_demo.py', 'annotation_demo2.py', 'anatomy of a matplotlib plot' mentioned in PR #524 [2]).
• separate sections for toolboxes (already exists)

These names are certainly up for debate. In addition, the plotting section may be too general, as discussed below (see Alternate gallery sections).

The current examples in the api and pylab_examples sections of the gallery would remain in those directories until they are cleaned up. After clean-up, they would be moved to one of the new gallery sections described above. "Clean-up" should involve:

• PEP8 clean-ups
• Commented-out code should be removed.
• Add introductory sentence or paragraph in the main docstring.
• Replace uses of pylab interface with pyplot (+ numpy, etc.).
• Each example should focus on a specific feature (which should be described in the docstring); tweaking unrelated to that feature should be removed. (This excludes examples in the showcase section, which will show more "polished" plots.)
• One figure per example file? (or maybe just display one figure in the gallery?)

Use of pylab should be demonstrated/discussed on a dedicated help page instead of the gallery examples.

Since clean-up could drastically change the displayed plot, it may be worthwhile to store the original example in an alternate gallery.

Instead of a section named plotting, it might be useful to use a finer-grained classification; for example:

• lines, bars, and markers
• shapes and collections
• images, contours, and fields
• pie and polar charts

See the following mailing list thread for more discussion on gallery organization: [3]. Also, here are a couple of alternate plot galleries for comparison/inspiration: [4], [5].

Tagging examples will also help users search the example gallery. Although tags would be a big win for users with specific goals, the plot gallery will remain the entry point to these examples, and sections could really help users navigate the gallery. Thus, tags are complementary to this reorganization.

[1]	http://github.com/matplotlib/matplotlib/pull/714

[2]	http://github.com/matplotlib/matplotlib/issues/524

[3]	http://matplotlib.1069221.n5.nabble.com/Matplotlib-gallery-td762.html#a33379091

[4]	http://www.loria.fr/~rougier/teaching/matplotlib/

[5]	http://www.gigawiz.com/aagraphs.html