8000 DOC : move MEP12 · matplotlib/matplotlib@579ecb8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 579ecb8

Browse files
tacaswelltacaswell
committed
DOC : move MEP12
1 parent 7103985 commit 579ecb8

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎doc/devel/MEP/MEP12.rst

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
=====================================
2+
MEP12: Improve Gallery and Examples
3+
=====================================
4+
.. contents::
5+
:local:
6+
7+
8+
Status
9+
======
10+
11+
**Progress**
12+
13+
Initial changes added in 1.3. Conversion of the gallery is on-going.
14+
15+
Branches and Pull requests
16+
==========================
17+
18+
#1623, #1924, #2181
19+
20+
PR `#2474 <https://github.com/matplotlib/matplotlib/pull/2474`>_
21+
demonstrates a single example being cleaned up and moved to the
22+
appropriate section.
23+
24+
Abstract
25+
========
26+
27+
Reorganizing the matplotlib plot gallery would greatly simplify
28+
navigation of the gallery. In addition, examples should be cleaned-up
29+
and simplified for clarity.
30+
31+
32+
Detailed description
33+
====================
34+
35+
The matplotlib gallery was recently set up to split examples up into
36+
sections. As discussed in that PR [1]_, the current example sections
37+
(``api``, ``pylab_examples``) aren't terribly useful to users: New
38+
sections in the gallery would help users find relevant examples.
39+
40+
These sections would also guide a cleanup of the examples: Initially,
41+
all the current examples would remain and be listed under their
42+
current directories. Over time, these examples could be cleaned up
43+
and moved into one of the new sections.
44+
45+
This process allows users to easily identify examples that need to be
46+
cleaned up; i.e. anything in the ``api`` and ``pylab_examples``
47+
directories.
48+
49+
50+
Implementation
51+
==============
52+
53+
1. Create new gallery sections. [Done]
54+
2. Clean up examples and move them to the new gallery sections (over the course
55+
of many PRs and with the help of many users/developers). [In progress]
56+
57+
Gallery sections
58+
----------------
59+
60+
The naming of sections is critical and will guide the clean-up
61+
effort. The current sections are:
62+
63+
* Lines, bars, and markers (more-or-less 1D data)
64+
* Shapes and collections
65+
* Statistical plots
66+
* Images, contours, and fields
67+
* Pie and polar charts: Round things
68+
* Color
69+
* Text, labels, and annotations
70+
* Ticks and spines
71+
* Subplots, axes, and figures
72+
* Specialty plots (e.g., sankey, radar, tornado)
73+
* Showcase (plots with tweaks to make them publication-quality)
74+
* separate sections for toolboxes (already exists: 'mplot3d',
75+
'axes_grid', 'units', 'widgets')
76+
77+
These names are certainly up for debate. As these sections grow, we
78+
should reevaluate them and split them up as necessary.
79+
80+
81+
Clean up guidelines
82+
-------------------
83+
84+
The current examples in the ``api`` and ``pylab_examples`` sections of
85+
the gallery would remain in those directories until they are cleaned
86+
up. After clean-up, they would be moved to one of the new gallery
87+
sections described above. "Clean-up" should involve:
88+
89+
* PEP8_ clean-ups (running `flake8
90+
<https://pypi.python.org/pypi/flake8>`_, or a similar checker, is
91+
highly recommended)
92+
* Commented-out code should be removed.
93+
* Add introductory sentence or paragraph in the main docstring. See
94+
`6d1b8a2
95+
<https://github.com/tonysyu/matplotlib/commit/6d1b8a2ef277091eb718690e4443e6fa30cbc488>`_.
96+
* Replace uses of ``pylab`` interface with ``pyplot`` (+ ``numpy``,
97+
etc.). See `c25ef1e
98+
<https://github.com/tonysyu/matplotlib/commit/c25ef1e02b3a0ecb279492409dac0de9b3d2c0e2>`_
99+
* Remove shebang line, e.g.:
100+
101+
#!/usr/bin/env python
102+
103+
* Use consistent imports. In particular:
104+
105+
import numpy as np
106+
107+
import matplotlib.pyplot as plt
108+
109+
Avoid importing specific functions from these modules (e.g. ``from
110+
numpy import sin``)
111+
112+
* Each example should focus on a specific feature (excluding
113+
``showcase`` examples, which will show more "polished"
114+
plots). Tweaking unrelated to that feature should be removed. See
115+
`f7b2217
116+
<https://github.com/tonysyu/matplotlib/commit/f7b2217a1f92343e8aca0684d19c9915cc2e8674>`_,
117+
`e57b5fc
118+
<https://github.com/tonysyu/matplotlib/commit/e57b5fc31fbad83ed9c43c77ef15368efdcb9ec1>`_,
119+
and `1458aa8
120+
<https://github.com/tonysyu/matplotlib/commit/1458aa87c5eae9dd99e141956a6adf7a0f3c6707>`_
121+
122+
Use of ``pylab`` should be demonstrated/discussed on a dedicated help
123+
page instead of the gallery examples.
124+
125+
**Note:** When moving an existing example, you should search for
126+
references to that example. For example, the API documentation for
127+
`axes.py` and `pyplot.py` may use these examples to generate
128+
plots. Use your favorite search tool (e.g., grep, ack, `grin
129+
<http://pypi.python.org/pypi/grin>`_, `pss
130+
<http://pypi.python.org/pypi/pss>`_) to search the matplotlib
131+
package. See `2dc9a46
132+
<https://github.com/tonysyu/matplotlib/commit/2dc9a4651e5e566afc0866c603aa8d06aaf32b71>`_
133+
and `aa6b410
134+
<https://github.com/tonysyu/matplotlib/commit/aa6b410f9fa085ccf5f4f962a6f26af5beeae7af>`_
135+
136+
137+
Additional suggestions
138+
~~~~~~~~~~~~~~~~~~~~~~
139+
140+
* Provide links (both ways) between examples and API docs for the
141+
methods/objects used. (issue `#2222
142+
<https://github.com/matplotlib/matplotlib/issues/2222>`_)
143+
* Use ``plt.subplots`` (note trailing "s") in preference over
144+
``plt.subplot``.
145+
* Rename the example to clarify it's purpose. For example, the most
146+
basic demo of ``imshow`` might be ``imshow_demo.py``, and one
147+
demonstrating different interpolation settings would be
148+
``imshow_demo_interpolation.py`` (*not* ``imshow_demo2.py``).
149+
* Split up examples that try to do too much. See `5099675
150+
<https://github.com/tonysyu/matplotlib/commit/509967518ce5ce5ba31edf12486ffaa344e748f2>`_
151+
and `fc2ab07
152+
<https://github.com/tonysyu/matplotlib/commit/fc2ab07cc586abba4c024d8c0d841c4357a3936f>`_
153+
* Delete examples that don't show anything new.
154+
* Some examples exercise esoteric features for unit testing. These
155+
tweaks should be moved out of the gallery to an example in the
156+
``unit`` directory located in the root directory of the package.
157+
* Add plot titles to clarify intent of the example. See `bd2b13c
158+
<https://github.com/tonysyu/matplotlib/commit/bd2b13c54bf4aa2058781b9a805d68f2feab5ba5>`_
159+
160+
161+
Backward compatibility
162+
======================
163+
164+
The website for each Matplotlib version is readily accessible, so
165+
users who want to refer to old examples can still do so.
166+
167+
168+
Alternatives
169+
============
170+
171+
Tags
172+
----
173+
174+
Tagging examples will also help users search the example gallery. Although tags
175+
would be a big win for users with specific goals, the plot gallery will remain
176+
the entry point to these examples, and sections could really help users
177+
navigate the gallery. Thus, tags are complementary to this reorganization.
178+
179+
180+
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
181+
182+
.. [1] http://github.com/matplotlib/matplotlib/pull/714
183+
.. [2] http://github.com/matplotlib/matplotlib/issues/524
184+
.. [3] http://matplotlib.1069221.n5.nabble.com/Matplotlib-gallery-td762.html#a33379091
185+
.. [4] http://www.loria.fr/~rougier/teaching/matplotlib/
186+
.. [5] http://www.gigawiz.com/aagraphs.html
187+
.. [6] http://www.loria.fr/~rougier/coding/gallery/

‎doc/devel/MEP/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ Matplotlib Enhancement Proposals
1515
template
1616
MEP10
1717
MEP11
18+
MEP12
1819
MEP25

0 commit comments

Comments
 (0)
0