1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
|
=========================
Documentation style guide
=========================
This guide contains best practices for the language and formatting of Matplotlib
documentation.
.. seealso::
For more information about contributing, see the :ref:`documenting-matplotlib`
section.
Expository language
===================
For explanatory writing, the following guidelines are for clear and concise
language use.
Terminology
-----------
There are several key terms in Matplotlib that are standards for
reliability and consistency in documentation. They are not interchangeable.
.. table::
:widths: 15, 15, 35, 35
+------------------+--------------------------+--------------+--------------+
| Term | Description | Correct | Incorrect |
+==================+==========================+==============+==============+
| |Figure| | Matplotlib working space | - *For | - "The figure|
| | for programming. | Matplotlib | is the |
| | | objects*: | working |
| | | Figure, | space for |
| | | "The Figure| visuals." |
| | | is the | - "Methods in|
| | | working | the figure |
| | | space for | provide the|
| | | the visual.| visuals." |
| | | - *Referring | - "The |
| | | to class*: | |Figure| |
| | | |Figure|, | Four |
| | | "Methods | leglock is |
| | | within the | a wrestling|
| | | |Figure| | move." |
| | | provide the| |
| | | visuals." | |
| | | - *General | |
| | | language*: | |
| | | figure, | |
| | | "Michelle | |
| | | Kwan is a | |
| | | famous | |
| | | figure | |
| | | skater." | |
+------------------+--------------------------+--------------+--------------+
| |Axes| | Subplots within Figure. | - *For | - "The axes |
| | Contains plot elements | Matplotlib | methods |
| | and is responsible for | objects*: | transform |
| | plotting and configuring | Axes, "An | the data." |
| | additional details. | Axes is a | - "Each |
| | | subplot | |Axes| is |
| | | within the | specific to|
| | | Figure." | a Figure." |
| | | - *Referring | - "The |
| | | to class*: | musicians |
| | | |Axes|, | on stage |
| | | "Each | call their |
| | | |Axes| is | guitars |
| | | specific to| Axes." |
| | | one | - "The point |
| | | Figure." | where the |
| | | - *General | Axes meet |
| | | language*: | is the |
| | | axes, "Both| origin of |
| | | loggers and| the |
| | | lumberjacks| coordinate |
| | | use axes to| system." |
| | | chop wood."| |
| | | OR "There | |
| | | are no | |
| | | standard | |
| | | names for | |
| | | the | |
| | | coordinates| |
| | | in the | |
| | | three | |
| | | axes." | |
| | | (Plural of | |
| | | axis) | |
+------------------+--------------------------+--------------+--------------+
| |Artist| | Broad variety of | - *For | - "Configure |
| | Matplotlib objects that | Matplotlib | the legend |
| | display visuals. | objects*: | artist with|
| | | Artist, | its |
| | | "Artists | respective |
| | | display | method." |
| | | visuals and| - "There is |
| | | are the | an |
| | | visible | |Artist| |
| | | elements | for that |
| | | when | visual in |
| | | rendering a| the graph."|
| | | Figure." | - "Some |
| | | - *Referring | Artists |
| | | to class*: | became |
| | | |Artist| , | famous only|
| | | "Each | by |
| | | |Artist| | accident." |
| | | has | |
| | | respective | |
| | | methods and| |
| | | functions."| |
| | | - *General | |
| | | language*: | |
| | | artist, | |
| | | "The | |
| | | artist in | |
| | | the museum | |
| | | is from | |
| | | France." | |
+------------------+--------------------------+--------------+--------------+
| |Axis| | Human-readable single | - *For | - "Plot the |
| | dimensional object | Matplotlib | graph onto |
| | of reference marks | objects*: | the axis." |
| | containing ticks, tick | Axis, "The | - "Each Axis |
| | labels, spines, and | Axis for | is usually |
| | edges. | the bar | named after|
| | | chart is a | the |
| | | separate | coordinate |
| | | Artist." | which is |
| | | (plural, | measured |
| | | Axis | along it." |
| | | objects) | - "In some |
| | | - *Referring | computer |
| | | to class*: | graphics |
| | | |Axis|, | contexts, |
| | | "The | the |
| | | |Axis| | ordinate |
| | | contains | |Axis| may |
| | | respective | be oriented|
| | | XAxis and | downwards."|
| | | YAxis | |
| | | objects." | |
| | | - *General | |
| | | language*: | |
| | | axis, | |
| | | "Rotation | |
| | | around a | |
| | | fixed axis | |
| | | is a | |
| | | special | |
| | | case of | |
| | | rotational | |
| | | motion." | |
+------------------+--------------------------+--------------+--------------+
| Axes interface | Usage pattern in which | - Axes | - explicit |
| | one calls methods on | interface | interface |
| | Axes and Figure (and | - call | - object |
| | sometimes other Artist) | methods on | oriented |
| | objects to configure the | the Axes / | - OO-style |
| | plot. | Figure | - OOP |
| | | object | |
+------------------+--------------------------+--------------+--------------+
| pyplot interface | Usage pattern in which | - ``pyplot`` | - implicit |
| | one only calls `.pyplot` | interface | interface |
| | functions to configure | - call | - MATLAB like|
| | the plot. | ``pyplot`` | - Pyplot |
| | | functions | |
+------------------+--------------------------+--------------+--------------+
.. |Figure| replace:: :class:`~matplotlib.figure.Figure`
.. |Axes| replace:: :class:`~matplotlib.axes.Axes`
.. |Artist| replace:: :class:`~matplotlib.artist.Artist`
.. |Axis| replace:: :class:`~matplotlib.axis.Axis`
Grammar
-------
Subject
^^^^^^^
Use second-person imperative sentences for directed instructions specifying an
action. Second-person pronouns are for individual-specific contexts and
possessive reference.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| Install Matplotlib from the source | You can install Matplotlib from the|
| directory using the Python ``pip`` | source directory. You can find |
| installer program. Depending on | additional support if you are |
| your operating system, you may need| having trouble with your |
| additional support. | installation. |
+------------------------------------+------------------------------------+
Tense
^^^^^
Use present simple tense for explanations. Avoid future tense and other modal
or auxiliary verbs when possible.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| The fundamental ideas behind | Matplotlib will take data and |
| Matplotlib for visualization | transform it through functions and |
| involve taking data and | methods. They can generate many |
| transforming it through functions | kinds of visuals. These will be the|
| and methods. | fundamentals for using Matplotlib. |
+------------------------------------+------------------------------------+
Voice
^^^^^
Write in active sentences. Passive voice is best for situations or conditions
related to warning prompts.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| The function ``plot`` generates the| The graph is generated by the |
| graph. | ``plot`` function. |
+------------------------------------+------------------------------------+
| An error message is returned by the| You will see an error message from |
| function if there are no arguments.| the function if there are no |
| | arguments. |
+------------------------------------+------------------------------------+
Sentence structure
^^^^^^^^^^^^^^^^^^
Write with short sentences using Subject-Verb-Object order regularly. Limit
coordinating conjunctions in sentences. Avoid pronoun references and
subordinating conjunctive phrases.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| The ``pyplot`` module in Matplotlib| The ``pyplot`` module in Matplotlib|
| is a collection of functions. These| is a collection of functions which |
| functions create, manage, and | create, manage, and manipulate the |
| manipulate the current Figure and | current Figure and plotting area. |
| plotting area. | |
+------------------------------------+------------------------------------+
| The ``plot`` function plots data | The ``plot`` function plots data |
| to the respective Axes. The Axes | within its respective Axes for its |
| corresponds to the respective | respective Figure. |
| Figure. | |
+------------------------------------+------------------------------------+
| The implicit approach is a | Users that wish to have convenient |
| convenient shortcut for | shortcuts for generating plots use |
| generating simple plots. | the implicit approach. |
+------------------------------------+------------------------------------+
Formatting
==========
The following guidelines specify how to incorporate code and use appropriate
formatting for Matplotlib documentation.
Code
----
Matplotlib is a Python library and follows the same standards for
documentation.
Comments
^^^^^^^^
Examples of Python code have comments before or on the same line.
.. table::
:width: 100%
:widths: 50, 50
+---------------------------------------+---------------------------------+
| Correct | Incorrect |
+=======================================+=================================+
| :: | :: |
| | |
| # Data | years = [2006, 2007, 2008] |
| years = [2006, 2007, 2008] | # Data |
+---------------------------------------+ |
| :: | |
| | |
| years = [2006, 2007, 2008] # Data | |
+---------------------------------------+---------------------------------+
Outputs
^^^^^^^
When generating visuals with Matplotlib using ``.py`` files in examples,
display the visual with `matplotlib.pyplot.show` to display the visual.
Keep the documentation clear of Python output lines.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| :: | :: |
| | |
| plt.plot([1, 2, 3], [1, 2, 3]) | plt.plot([1, 2, 3], [1, 2, 3]) |
| plt.show() | |
+------------------------------------+------------------------------------+
| :: | :: |
| | |
| fig, ax = plt.subplots() | fig, ax = plt.subplots() |
| ax.plot([1, 2, 3], [1, 2, 3]) | ax.plot([1, 2, 3], [1, 2, 3]) |
| fig.show() | |
+------------------------------------+------------------------------------+
reStructuredText
----------------
Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to
transform these documents into appropriate formats for accessibility and
visibility.
- `reStructuredText Specifications <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_
- `Quick Reference Document <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_
Lists
^^^^^
Bulleted lists are for items that do not require sequencing. Numbered lists are
exclusively for performing actions in a determined order.
.. table::
:width: 100%
:widths: 50, 50
+------------------------------------+------------------------------------+
| Correct | Incorrect |
+====================================+====================================+
| The example uses three graphs. | The example uses three graphs. |
+------------------------------------+------------------------------------+
| - Bar | 1. Bar |
| - Line | 2. Line |
| - Pie | 3. Pie |
+------------------------------------+------------------------------------+
| These four steps help to get | The following steps are important |
| started using Matplotlib. | to get started using Matplotlib. |
+------------------------------------+------------------------------------+
| 1. Import the Matplotlib library. | - Import the Matplotlib library. |
| 2. Import the necessary modules. | - Import the necessary modules. |
| 3. Set and assign data to work on.| - Set and assign data to work on. |
| 4. Transform data with methods and| - Transform data with methods and |
| functions. | functions. |
+------------------------------------+------------------------------------+
Tables
^^^^^^
Use ASCII tables with reStructuredText standards in organizing content.
Markdown tables and the csv-table directive are not accepted.
.. table::
:width: 100%
:widths: 50, 50
+--------------------------------+----------------------------------------+
| Correct | Incorrect |
+================================+========================================+
| +----------+----------+ | :: |
| | Correct | Incorrect| | |
| +==========+==========+ | | Correct | Incorrect | |
| | OK | Not OK | | | ------- | --------- | |
| +----------+----------+ | | OK | Not OK | |
| | |
+--------------------------------+----------------------------------------+
| :: | :: |
| | |
| +----------+----------+ | .. csv-table:: |
| | Correct | Incorrect| | :header: "correct", "incorrect" |
| +==========+==========+ | :widths: 10, 10 |
| | OK | Not OK | | |
| +----------+----------+ | "OK ", "Not OK" |
| | |
+--------------------------------+ |
| :: | |
| | |
| =========== =========== | |
| Correct Incorrect | |
| =========== =========== | |
| OK Not OK | |
| =========== =========== | |
| | |
+--------------------------------+----------------------------------------+
Additional resources
====================
This style guide is not a comprehensive standard. For a more thorough
reference of how to contribute to documentation, see the links below. These
resources contain common best practices for writing documentation.
* `Python Developer's Guide <https://devguide.python.org/documenting/#documenting-python>`_
* `Google Developer Style Guide <https://developers.google.com/style>`_
* `IBM Style Guide <https://www.oreilly.com/library/view/the-ibm-style/9780132118989/>`_
* `Red Hat Style Guide <https://stylepedia.net/style/#grammar>`_
|
