.. author:: Tony S Yu

Progress

Initial changes added in 1.3. Conversion of the gallery is on-going.

#1623, #1924, #2181

PR#2474 <https://github.com/matplotlib/matplotlib/pull/2474>_ demonstrates a single example being cleaned up and moved to the appropriate section.

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

The matplotlib gallery was recently set up 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 thegallery would help users find relevant examples.

These sections would also guide a cleanup of the examples: Initially, all thecurrent examples would remain and be listed under their current directories.Over time, these examples could be cleaned up and moved into one of the newsections.

This process allows users to easily identify examples that need to be cleanedup; i.e. anything in theapi andpylab_examples directories.

1. Create new gallery sections. [Done]
2. Clean up examples and move them to the new gallery sections (over the courseof many PRs and with the help of many users/developers). [In progress]

The naming of sections is critical and will guide the clean-up effort. Thecurrent sections are:

• Lines, bars, and markers (more-or-less 1D data)
• Shapes and collections
• Statistical plots
• Images, contours, and fields
• Pie and polar charts: Round things
• Color
• Text, labels, and annotations
• Ticks and spines
• Subplots, axes, and figures
• Specialty plots (e.g., sankey, radar, tornado)
• Showcase (plots with tweaks to make them publication-quality)
• separate sections for toolboxes (already exists: 'mplot3d', 'axes_grid', 'units', 'widgets')

These names are certainly up for debate. As these sections grow, we should reevaluate them and split them up as necessary.

The current examples in theapi andpylab_examples sections of thegallery would remain in those directories until they are cleaned up. Afterclean-up, they would be moved to one of the new gallery sections describedabove. "Clean-up" should involve:

• PEP8 clean-ups (runningflake8, or a similar checker, is highly recommended)

• Commented-out code should be removed.

• Add introductory sentence or paragraph in the main docstring. See6d1b8a2.

• Replace uses ofpylab interface withpyplot (+numpy, etc.). Seec25ef1e

• Remove shebang line, e.g.:

  #!/usr/bin/env python

• Use consistent imports. In particular:

  import numpy as np

  import matplotlib.pyplot as plt

  Avoid importing specific functions from these modules (e.g.from numpy import sin)

• Each example should focus on a specific feature (excludingshowcaseexamples, which will show more "polished" plots). Tweaking unrelated to thatfeature should be removed. Seef7b2217,e57b5fc, and1458aa8

Use ofpylab should be demonstrated/discussed on a dedicated help pageinstead of the gallery examples.

Note: When moving an existing example, you should search for references to that example.For example, the API documentation foraxes.py andpyplot.py may use theseexamples to generate plots. Use your favorite search tool (e.g., grep, ack,grin,pss)to search the matplotlib package. See2dc9a46 andaa6b410

• Provide links (both ways) between examples and API docs for the methods/objects used. (issue#2222)
• Useplt.subplots (note trailing "s") in preference overplt.subplot.
• Rename the example to clarify it's purpose. For example, the most basicdemo ofimshow might beimshow_demo.py, and one demonstratingdifferent interpolation settings would beimshow_demo_interpolation.py(notimshow_demo2.py).
• Split up examples that try to do too much. See5099675 andfc2ab07
• Delete examples that don't show anything new.
• Some examples exercise esoteric features for unit testing. These tweaksshould be moved out of the gallery to an example in theunit directorylocated in the root directory of the package.
• Add plot titles to clarify intent of the example. Seebd2b13c

The website for each Matplotlib version is readily accessible, so users whowant to refer to old examples can still do so.

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