8000 Content guide for usage/demo docs · matplotlib/matplotlib@e36416f · GitHub
[go: up one dir, main page]
Skip to content

Commit e36416f

Browse files
story645timhoffmesibinga
committed
Content guide for usage/demo docs
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Co-authored-by: Eva Sibinga <46283995+esibinga@users.noreply.github.com>
1 parent d3ee51b commit e36416f

File tree

2 files changed

+274
-0
lines changed

2 files changed

+274
-0
lines changed

‎doc/devel/content_guide.rst

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
.. _documenting-content:
2+
3+
******************
4+
Content guidelines
5+
******************
6+
7+
The following content guidelines aim to improve the consistency, cohesiveness, and
8+
organization of the documentation on using the library. Broadly, this documentations
9+
falls into one of these sections:
10+
11+
:ref:`plot_types`
12+
Summary of visualization techniques implemented as high-level API
13+
14+
:ref:`users-guide-explain`
15+
| Explanations of key concepts and core functionality,
16+
| e.g. :ref:`what-is-a-backend`, :ref:`colors_def`, and :ref:`event_handling`
17+
18+
:ref:`tutorials`
19+
| Lessons on developing complex visualizations,
20+
| e.g. :doc:`making an annotated styled bar chart<../tutorials/lifecycle>`
21+
22+
:ref:`examples-index`
23+
| Demonstrations of how to execute specific tasks,
24+
| e.g. :doc:`../gallery/animation/animated_histogram`, :doc:`../gallery/misc/bbox_intersect`
25+
26+
:ref:`api-reference`
27+
Descriptions of the public modules, objects, methods, and functions.
28+
29+
30+
.. _content-plot-types:
31+
32+
Plot types gallery
33+
==================
34+
35+
The plot type gallery displays a selection of the common visualization techniques that
36+
are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the
37+
plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged.
38+
39+
Format
40+
------
41+
* very short: 5-10 lines
42+
* self explanatory data
43+
* little to no customization.
44+
45+
46+
.. _content-user-guide:
47+
48+
User guide
49+
==========
50+
51+
The goal of the user guide is to explain how Matplotlib works to someone who is
52+
unfamiliar with the library. The focus is primarily on the functionality provided by the
53+
library.
54+
55+
Purpose
56+
-------
57+
58+
The aim of the user guide is to teach the conceptual abstractions on which the
59+
Matplotlib API is developed so that users can understand how to fit the individual
60+
components of the library together. Therefore, content should be concept oriented
61+
rather than focused on specific tasks, e.g.
62+
63+
Lines in Matplotlib
64+
65+
rather than *How do I make a squiggly yellow line?*
66+
67+
Audience
68+
--------
69+
70+
The Matplotlib audience encompasses a wide spectrum of users, from readers who are first
71+
getting introduced to using Matplotlib through the guide to experienced developers who
72+
want to make something extremely customizied. Instead of trying to write for the
73+
spectrum, documents should identify their audience so the reader can asses whether the
74+
document is appropriate for them.
75+
76+
For example, introductory documents should be written with the assumption that
77+
the reader does not yet know what Matplotlib calls a given visualization task nor
78+
how any task is accomplished in Matplotlib. Those documents should first introduce or
79+
define the object/module/concept that it is discussing and why it is important for the
80+
reader. e.g.
81+
82+
The `~.Line2D` class is an abstraction of a line and the ``LineCollection`` class is
83+
an abstraction of a set of lines. ``Line2D`` and ``LineCollection`` objects manage
84+
the properties and behavior of almost every line in an image. This means that one way
85+
to modify a line is to call methods on its underlying object.*
86+
87+
Documents that assume familarity with the library should, when possible, be explicit
88+
about what knowledge the audience is assumed to have, e.g.
89+
90+
91+
This guide assumes that the user understands the general concept of Artists, as
92+
explained in :doc:`../users/explain/artists/artist_intro`
93+
94+
Generally the user guide should be written with the assumption that the reader has
95+
read previous sections and documents should cross reference as necessary rather than
96+
duplicating information.
97+
98+
99+
Scope
100+
-----
101+
102+
Many concepts in Matplotlib assume a grounding in visualization, statistics, Python
103+
programming, and other topics to understand how they work. These concepts should be
104+
contextualized using common terminology, but the focus for all documents should not
105+
stray from the Matplotlib topic, e.g.
106+
107+
``Line2D`` objects take as input a list of pairwise coordinates (x,y) and generates
108+
line segments connecting each pair of points with the next pair in the list.
109+
110+
Here *pairwise coordinates* are not defined because it is a common term from math and
111+
therefore defining it is out of scope. For some terms, it may also be appropriate to
112+
link out to an explanation.
113+
114+
115+
Format
116+
------
117+
118+
When possible, the material is introduced in tightly scoped sections that build on top
119+
of each other, using teaching strategies called `chunking and scaffolding`_.
120+
Chunking is aimed at reducing `cognitive load`_ by keeping the focus of each section
121+
relatively small, and scaffolding lays out instructional material such that each section
122+
builds on the previous one.
123+
124+
For example, here the line object is introduced, then there is one example of using a
125+
method on the object. This primes the reader to better understand the example where the
126+
two concepts are combined, and then there is a link out to further functionality::
127+
128+
For example, here the ``plot`` method returns a line object ``ln``::
129+
130+
ln, _ = ax.plot([1,2,3], color='blue')
131+
132+
One of the properties of a line is its color.
133+
It can be modified using the ``set_color`` method of ``Line2D``::
134+
135+
ln.set_color('orange')
136+
137+
The line color resulting from this modification is orange:
138+
139+
fig, ax = plt.subplots()
140+
ln, _ = ax.plot([1,2,3], color='blue')
141+
ln.set_color('orange')
142+
143+
For a full list of methods see `~.Line2D`
144+
145+
For some examples, it may be preferable to take the inverse approach: start with
146+
the combined example and then unpack it into its pieces.
147+
148+
In general, this approach is aimed at helping the user develop a model of the concept
149+
by first defining it and then illustrating how that understanding facilitates better use
150+
of the library. In keeping with this goal, documents should also be tightly focused on
151+
one topic and link out to related material, e.g. linking to the `.Axes.plot`
152+
documentation rather then explaining it here.
153+
154+
155+
.. _`chunking and scaffolding`: https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing
156+
.. _`cognitive load`: https://carpentries.github.io/instructor-training/05-memory.html
157+
158+
.. _content-tutorials:
159+
160+
Tutorials
161+
=========
162+
163+
The goal of the tutorials is to teach the reader how to use Matplotlib to build a
164+
specific complex visualization. As opposed to the user guide where the functionality
165+
takes focus, in the tutorials the goal takes center stage.
166+
167+
Format
168+
------
169+
170+
As with the user guide, the tutorials should aim to unpack information in chunks and
171+
build on the previous section. As demonstrated, here it is used to walk with the user
172+
through the steps involved in animating a line plot. Generally the content is limited
173+
to describing what is happening at each stage- for example there's no explanation of
174+
why an update function is written-and instead the reader is linked to explanation.
175+
176+
177+
For example, where the user guide explains ``Line2D``, a tutorial on animating
178+
a sin wave would instruct the reader on setting the new location, eg::
179+
180+
First lets generate a sin wave::
181+
182+
x = np.linspace(0, 2*np.pi, 1000)
183+
y = np.sin(x)
184+
185+
Then we plot an empty line and capture the returned line object::
186+
187+
fig, ax = plt.subplot()
188+
l, _ = ax.plot(0,0)
189+
190+
Next we write a function that changes the plot on each frame::
191+
192+
def update(frame):
193+
194+
l.set_data(x[:i], y[:i])
195+
196+
Here we grow the sin curve on each update by setting the new x and y data::
197+
198+
Lastly we add an animation writer::
199+
200+
ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30)
201+
202+
Here we specify 30 milliseconds between each of the 40 frames.
203+
204+
Now lets put it all together so we can plot an animated sin curve::
205+
206+
x = np.linspace(0, 2*np.pi, 1000)
207+
y = np.sin(x)
208+
209+
fig, ax = plt.subplot()
210+
l, _ = ax.plot(0,0)
211+
212+
def update(frame):
213+
l.set_data(x[:i], y[:i])
214+
215+
ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30)
216+
217+
For more information on animations and lines, see:
218+
* :ref:`animations`
219+
* ``:ref:Line2d``.
220+
221+
222+
Also note that while the aim is to show how to animate a sin curve, the focus is always
223+
on making the animation. Generally explanations of domain should be limited to
224+
providing contextually necessary information, and tutorials that are heavily domain
225+
specific may be more appropriate for the Scientific Python
226+
`blog <https://blog.scientific-python.org/>`_.
227+
228+
229+
.. _content-examples:
230+
231+
Examples gallery
232+
================
233+
234+
The gallery of examples contains visual demonstrations of Matplotlib features. Gallery
235+
examples exist so that users can scan through visual examples. Unlike tutorials or user
236+
guides, gallery examples teach by demonstration, rather than by instruction or
237+
explanation.
238+
239+
Gallery examples should avoid instruction or excessive explanation except for brief
240+
clarifying code comments. Instead, they can tag related concepts and/or link to relevant
241+
tutorials or user guides.
242+
243+
Format
244+
------
245+
246+
All :ref:`examples-index` should aim to follow the following format:
247+
248+
* Title: 1-6 words, descriptive of content
249+
* Subtitle: 10-50 words, action-oriented description of the example subject
250+
* Image: a clear demonstration of the subject, showing edge cases and different
251+
applications if possible
252+
* Code + Text (optional): code, commented as appropriate + written text to add context
253+
if necessary
254+
255+
Example:
256+
257+
The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
258+
259+
* this example is "messy" in that it's hard to categorize, but the gallery is the right
260+
spot for it because it makes sense to find it by visual search
261+
* :doc:`../gallery/misc/bbox_intersect`
262+
263+
264+
.. _content-api:
265+
266+
API reference
267+
=============
268+
269+
The pages in :file:`doc/api` are purely technical definitions of layout; therefore new
270+
API reference documentation should be added to the module docstring to keep all API
271+
reference documentation about a module together. The API reference documentation
272+
describes the library interfaces, i.e. inputs, outputs, and expected behavior. For
273+
guidance on writing docstrings, see :ref:`writing-docstrings`

‎doc/devel/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,7 @@ Policies and guidelines
152152

153153
document
154154
style_guide
155+
content_guide
155156
tag_guidelines
156157

157158
.. grid-item-card::

0 commit comments

Comments
 (0)
0