8000 summary user guide · matplotlib/matplotlib@581d66c · GitHub
[go: up one dir, main page]
Skip to content

Commit 581d66c

Browse files
story645story645
committed
summary user guide
1 parent ed86a39 commit 581d66c

File tree

8 files changed

+299
-293
lines changed

8 files changed

+299
-293
lines changed

‎doc/devel/content_guide.rst

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
.. _documenting-content:
2+
3+
***************************
4+
Documentation content guide
5+
***************************
6+
7+
These guidelines aim to improve the consistency, cohesiveness, and organization of the
8+
:ref: documentation concerning using the library by broadly articulating the intended purpose,
9+
scope, and audience of each of the following sections:
10+
11+
:ref:`plot_types`
12+
| Summary of chart types that are implemented as high-level API
13+
14+
:ref:`User guide <users-guide-index>`
15+
| Explanations of features, components, and architecture.
16+
17+
:ref:`tutorials`
18+
| Lessons on developing visualizations
19+
20+
:ref:`examples-index`
21+
| Demonstrations of specific library features
22+
23+
:ref:`api-reference`
24+
| Descriptions of the public modules, objects, methods, and functions.
25+
26+
27+
.. note::
28+
29+
While parts of the current documentation may not yet align with these guidelines,
30+
we expect that new documentation contributions will also bring existing documentation
31+
into alignment.
32+
33+
.. note: based on note in https://matplotlib.org/3.7.3/devel/coding_guide.html
34+
35+
36+
37+
Summary
38+
==========
39+
40+
This content guide is heavily influenced by the `Diátaxis <https://diataxis.fr/>`_
41+
framework for technical documentation; this framework proposes that all
42+
technical documentation is roughly one of 4 types - tutorials, how-to-guides,
43+
technical reference, and explanation - and that the appropriate type is
44+
determined by whether the document focuses on *what* is x? (cognition) or *how*
45+
to do x?(action), and whether the document's purpose is *acquiring* (learning)
46+
or *applying* (using) skills.
47+
48+
Broadly, our documentation as viewed through a diátaxis lens:
49+
50+
.. list-table::
51+
:header-rows: 1
52+
:widths: 20 30 20 30
53+
54+
* - section
55+
- goal
56+
- type
57+
- example
58+
* - :ref:`plot_types`
59+
- View available chart types.
60+
- | `Reference <https://diataxis.fr/reference/>`_
61+
| what, use
62+
- :ref:`sphx_glr_plot_types_stats_pie.py`
63+
* - :ref:`User guide <users-guide-index>`
64+
- Understand features, components, and architecture
65+
- | `Explanation <https://diataxis.fr/explanation/>`_
66+
| what, learn
67+
- :ref:`annotations`
68+
* - :ref:`tutorials`
69+
- Work through the stages of building a visualization.
70+
- | `Tutorials <https://diataxis.fr/tutorials/>`_
71+
| how, learn
72+
- :ref:`sphx_glr_gallery_pie_and_polar_charts_pie_and_donut_labels.py`
73+
* - :ref:`examples-index`
74+
- Execute a visualization task.
75+
- | `How-to guides <https://diataxis.fr/how-to-guides/>`_
76+
| how, use
77+
- :ref:`sphx_glr_gallery_text_labels_and_annotations_rainbow_text.py`
78+
* - :ref:`api-reference`
79+
- Look up the input/output/behavior of public API.
80+
- | `Reference <https://diataxis.fr/reference/>`_
81+
| what, use
82+
- `.Axes.annotate`
83+
84+
Audience
85+
--------
86+
The Matplotlib audience encompasses a wide spectrum of readers, from users who are first
87+
getting introduced to using Matplotlib through the documentation to experienced developers
88+
who want to make something extremely customized. Instead of trying to write for the
89+
entire spectrum, each document should identify its band so that reader can assess
90+
whether the document is appropriate for them. The documentation should generally use the
91+
leveling of :doc:`tags <tag_guidelines>` and :ref:`issues <new_contributors>`, meaning
92+
that the audienced is identified based on how much contextual understanding of
93+
Matplotlib is a pre-requisite for following along with the document.
94+
95+
Documents can communicate this leveling through tags, location in the docs, and in text
96+
as appropriate. For example:
97+
98+
This guide assumes that the reader understands the general concept of Artists, as
99+
explained in :ref:`users_artists`
100+
101+
102+
Scope
103+
-----
104+
Many concepts in Matplotlib assume a grounding in visualization, statistics, Python
105+
programming, and other topics to understand how they work. These concepts should be
106+
contextualized using common terminology, but the focus for all documents should not
107+
stray from the Matplotlib topic. For example:
108+
109+
Some of the path components require multiple vertices to specify them: for example
110+
CURVE 3 is a `Bézier curve <https://en.wikipedia.org/wiki/B%C3%A9zier_curve>`_ with
111+
one control point and one end point, and CURVE4 has three vertices for the two
112+
control points and the end point. The example below shows a CURVE4 Bézier spline --
113+
the Bézier curve will be contained in the convex hull of the start point, the two
114+
control points, and the end point
115+
116+
117+
This explanation of drawing a curve using control points from :ref:`paths` never
118+
explicitly defines a *Bézier curve*, instead linking out to an external
119+
reference. This explanation is written in a manner where the definition of
120+
*Bézier curve* can be inferred from context and also understanding is not harmed if the
121+
reader does not infer the definition.
122+
123+
124+
.. _content-plot-types:
125+
126+
Plot types gallery
127+
==================
128+
129+
The plot type gallery displays a selection of the common visualization techniques that
130+
are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the
131+
plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged.
132+
133+
Format
134+
------
135+
* very short: 5-10 lines
136+
* self explanatory data
137+
* little to no customization.
138+
139+
.. _content-user-guide:
140+
141+
User guide
142+
==========
143+
144+
For more details, see :ref:`user-guide-content-detail`
145+
146+
.. toctree::
147+
:hidden:
148+
149+
user_guide
150+
151+
.. include:: user_guide.rst
152+
:start-after: summary-begin
153+
:end-before: summary-end
154+
155+
.. _content-tutorials:
156+
157+
Tutorials
158+
=========
159+
160+
The goal of the tutorials is to guide the reader through the stages of using
161+
Matplotlib to build a specific visualization. A tutorial describes what is
162+
happening at each stage of executing a visualization task and links to the
163+
user guide and API for explanations.
164+
165+
Format
166+
------
167+
168+
The sample tutorial here is trivial to highlight the step-wise format:
169+
170+
#. First we start by stating the objective:
171+
172+
.. code-block:: rst
173+
174+
The goal of this tutorial is to animate a sin wave.
175+
176+
#. Then we describe what needs to be in place to do the task:
177+
178+
.. code-block:: rst
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 walk the reader through each step of executing the task:
191+
192+
.. code-block:: rst
193+
194+
Next we write a function that changes the plot on each frame. Here we grow
195+
the sin curve on each update by setting the new x and y data::
196+
197+
def update(frame):
198+
199+
l.set_data(x[:i], y[:i])
200+
201+
Lastly we add an animation writer. Here we specify 30 milliseconds between each
202+
of the 40 frames::
203+
204+
ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30)
205+
206+
#. Then we summarize by putting all the steps together:
207+
208+
.. code-block:: rst
209+
210+
Now lets put it all together so we can plot an animated sin curve::
211+
212+
x = np.linspace(0, 2*np.pi, 1000)
213+
y = np.sin(x)
214+
215+
fig, ax = plt.subplot()
216+
l, _ = ax.plot(0,0)
217+
218+
def update(frame):
219+
l.set_data(x[:i], y[:i])
220+
221+
ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30)
222+
223+
#. Finally, we close with a call to action to learn about the underlying concepts:
224+
225+
.. code-block:: rst
226+
227+
For more information on animations and lines, see:
228+
* :ref:`animations`
229+
* ``:ref:Line2d``
230+
231+
Please note that explanations of domain should be limited to providing
232+
contextually necessary information, and tutorials that are heavily domain
233+
specific may be more appropriate for the Scientific Python
234+
`blog <https://blog.scientific-python.org/>`_.
235+
236+
237+
238+
.. _content-examples:
239+
240+
Examples gallery
241+
================
242+
243+
The gallery of examples contains visual demonstrations of Matplotlib features. Gallery
244+
examples exist so that readers can scan through visual examples. Unlike tutorials or
245+
user guides, gallery examples teach by demonstration, rather than by instruction or
246+
explanation.
247+
248+
Gallery examples should avoid instruction or excessive explanation except for brief
249+
clarifying code comments. Instead, they can tag related concepts and/or link to relevant
250+
tutorials or user guides.
251+
252+
Format
253+
------
254+
255+
All :ref:`examples-index` should aim to follow the following format:
256+
257+
* Title: 1-6 words, descriptive of content
258+
* Subtitle: 10-50 words, action-oriented description of the example subject
259+
* Image: a clear demonstration of the subject, showing edge cases and different
260+
applications if possible
261+
* Code + Text (optional): code, commented as appropriate + written text to add context
262+
if necessary
263+
264+
Example:
265+
266+
The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
267+
268+
* this example is "messy" in that it's hard to categorize, but the gallery is the right
269+
spot for it because it makes sense to find it by visual search
270+
* :ref:`sphx_glr_gallery_misc_bbox_intersect.py`
271+
272+
273+
.. _content-api:
274+
275+
API reference
276+
=============
277+
278+
The API reference documentation describes the library interfaces, e.g. inputs, outputs,
279+
and expected behavior. See :ref:`writing-docstrings` for guidance on writing docstrings.
280+
281+
The pages in :file:`doc/api` are purely technical definitions of layout; therefore new
282+
API reference documentation should be added to the module docstrings. This placement
283+
keeps all API reference documentation about a module in the same file.

‎doc/devel/content_guide/api.rst

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎doc/devel/content_guide/examples.rst

Lines changed: 0 additions & 33 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0