MEP12: Improve Gallery and Examples#

Status#

Progress

Initial changes added in 1.3. Conversion of the gallery is on-going.29 September 2015 - The lastpylab_examples wherepylab is imported hasbeen converted over to usematplotlib.pyplot andnumpy.

Branches and Pull requests#

#1623, #1924, #2181

PR#2474demonstrates a single example being cleaned up and moved to theappropriate section.

Abstract#

Reorganizing the matplotlib plot gallery would greatly simplifynavigation of the gallery. In addition, examples should be cleaned-upand simplified for clarity.

Detailed description#

The matplotlib gallery was recently set up to split examples up intosections. As discussed in that PR[1], the current example sections(api,pylab_examples) aren't terribly useful to users: Newsections 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 theircurrent directories. Over time, these examples could be cleaned upand moved into one of the new sections.

This process allows users to easily identify examples that need to becleaned up; i.e. anything in theapi andpylab_examplesdirectories.

Implementation#

  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]

Gallery sections#

The naming of sections is critical and will guide the clean-upeffort. The current 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, weshould reevaluate them and split them up as necessary.

Clean up guidelines#

The current examples in theapi andpylab_examples sections ofthe gallery would remain in those directories until they are cleanedup. After clean-up, they would be moved to one of the new gallerysections described above. "Clean-up" should involve:

  • sphinx-gallery docstrings:a title and a description of the example formatted as follows, at the top ofthe example:

    """===============================Colormaps alter your perception===============================Here I plot the function.. math:: f(x, y) = \sin(x) + \cos(y)with different colormaps. Look at how colormaps alter your perception!"""

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

  • Commented-out code should be removed.

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

  • Remove shebang line, e.g.:

    #!/usr/bin/env python

  • Use consistent imports. In particular:

    importnumpyasnpimportmatplotlib.pyplotasplt

    Avoid importing specific functions from these modules (e.g.fromnumpyimportsin)

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

Use ofpylab should be demonstrated/discussed on a dedicated helppage instead of the gallery examples.

Note: When moving an existing example, you should search forreferences to that example. For example, the API documentation foraxes.py andpyplot.py may use these examples to generateplots. Use your favorite search tool (e.g., grep, ack,grin,pss) to search the matplotlibpackage. See2dc9a46andaa6b410

Additional suggestions#

  • Provide links (both ways) between examples and API docs for themethods/objects used. (issue#2222)

  • Useplt.subplots (note trailing "s") in preference overplt.subplot.

  • Rename the example to clarify it's purpose. For example, the mostbasic demo ofimshow might beimshow_demo.py, and onedemonstrating different interpolation settings would beimshow_demo_interpolation.py (notimshow_demo2.py).

  • Split up examples that try to do too much. See5099675andfc2ab07

  • Delete examples that don't show anything new.

  • Some examples exercise esoteric features for unit testing. Thesetweaks should be moved out of the gallery to an example in theunit directory located in the root directory of the package.

  • Add plot titles to clarify intent of the example. Seebd2b13c

Backward compatibility#

The website for each Matplotlib version is readily accessible, sousers who want to refer to old examples can still do so.

Alternatives#

Tags#

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.

[1]

matplotlib/matplotlib#714