Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit d1f3e10

Browse filesBrowse files
KojoleyNelleV
Kojoley
and
NelleV
authored
Backport PR #11495 on branch v2.2.x (Update the documentation… (#16139)
Backport PR #11495 on branch v2.2.x (Update the documentation guidelines) Co-authored-by: Nelle Varoquaux <nelle.varoquaux@gmail.com>
2 parents 2ddd1c6 + 9e44bba commit d1f3e10
Copy full SHA for d1f3e10

File tree

Expand file treeCollapse file tree

2 files changed

+164
-95
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+164
-95
lines changed

‎doc/_static/mpl.css

Copy file name to clipboardExpand all lines: doc/_static/mpl.css
+4Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,10 @@ dl.glossary dt {
151151
font-size: 1.1em;
152152
}
153153

154+
dl.docutils dt {
155+
font-weight: bold;
156+
}
157+
154158
pre a {
155159
color: inherit;
156160
text-decoration: none;

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+160-95Lines changed: 160 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
Writing documentation
55
=====================
66

7+
.. contents:: Contents
8+
:depth: 2
9+
:local:
10+
:backlinks: top
11+
:class: multicol-toc
12+
13+
714
Getting started
815
===============
916

@@ -214,38 +221,52 @@ is better than:
214221
In addition, since underscores are widely used by Sphinx itself, use
215222
hyphens to separate words.
216223

224+
.. _referring-to-other-code:
217225

218226
Referring to other code
219227
-----------------------
220228

221229
To link to other methods, classes, or modules in Matplotlib you can use
222230
back ticks, for example:
223231

224-
.. code-block:: python
232+
.. code-block:: rst
225233
226-
`~matplotlib.collections.LineCollection`
234+
`matplotlib.collections.LineCollection`
227235
228-
returns a link to the documentation of
229-
`~matplotlib.collections.LineCollection`. For the full path of the
230-
class to be shown, omit the tilde:
236+
generates a link like this: `matplotlib.collections.LineCollection`.
231237

232-
.. code-block:: python
238+
*Note:* We use the sphinx setting ``default_role = 'obj'`` so that you don't
239+
have to use qualifiers like ``:class:``, ``:func:``, ``:meth:`` and the likes.
233240

234-
`matplotlib.collections.LineCollection`
241+
Often, you don't want to show the full package and module name. As long as the
242+
target is unanbigous you can simply leave them out:
243+
244+
.. code-block:: rst
235245
236-
to get `matplotlib.collections.LineCollection`. It is often not
237-
necessary to fully specify the class hierarchy unless there is a namespace
238-
collision between two packages:
246+
`.LineCollection`
239247
240-
.. code-block:: python
248+
and the link still works: `.LineCollection`.
249+
250+
If there are multiple code elements with the same name (e.g. ``plot()`` is a
251+
method in multiple classes), you'll have to extend the definition:
252+
253+
.. code-block:: rst
254+
255+
`.pyplot.plot` or `.Axes.plot`
256+
257+
These will show up as `.pyplot.plot` or `.Axes.plot`. To still show only the
258+
last segment you can add a tilde as prefix:
259+
260+
.. code-block:: rst
241261
242-
`~.LineCollection`
262+
`~.pyplot.plot` or `~.Axes.plot`
243263
244-
links just as well: `~.LineCollection`.
264+
will render as `~.pyplot.plot` or `~.Axes.plot`.
245265

246-
Other packages can also be linked via ``intersphinx``:
266+
Other packages can also be linked via
267+
`intersphinx <http://www.sphinx-doc.org/en/master/ext/intersphinx.html>`_:
247268

248-
.. code-block:: Python
269+
.. code-block:: rst
249270
250271
`numpy.mean`
251272
@@ -297,13 +318,19 @@ when the documentation is built.
297318
Writing docstrings
298319
==================
299320

300-
Much of the documentation lives in "docstrings". These are comment blocks
301-
in source code that explain how the code works. All new or edited docstrings
302-
should conform to the numpydoc guidelines. These split the docstring into a
303-
number of sections - see the `numpy documentation howto`_
304-
for more details and a guide to how docstrings should be formatted. Much of
305-
the ReST_ syntax discussed above (:ref:writing-rest-pages) can be used for
306-
links and references. These docstrings eventually populate the
321+
Most of the API documentation is written in docstrings. These are comment
322+
blocks in source code that explain how the code works.
323+
324+
.. note::
325+
326+
Some parts of the documentation do not yet conform to the current
327+
documentation style. If in doubt, follow the rules given here and not what
328+
you may see in the source code. Pull requests updating docstrings to
329+
the current style are very welcome.
330+
331+
All new or edited docstrings should conform to the `numpydoc docstring guide`_.
332+
Much of the ReST_ syntax discussed above (:ref:`writing-rest-pages`) can be
333+
used for links and references. These docstrings eventually populate the
307334
:file:`doc/api` directory and form the reference documentation for the
308335
library.
309336

@@ -314,21 +341,21 @@ An example docstring looks like:
314341

315342
.. code-block:: python
316343
317-
def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
318-
label='', **kwargs):
344+
def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
345+
label='', **kwargs):
319346
"""
320347
Plot horizontal lines at each *y* from *xmin* to *xmax*.
321348
322349
Parameters
323350
----------
324-
y : scalar or sequence of scalar
351+
y : float or array-like
325352
y-indexes where to plot the lines.
326353
327-
xmin, xmax : scalar or 1D array_like
354+
xmin, xmax : float or array-like
328355
Respective beginning and end of each line. If scalars are
329-
provided, all lines will have same length.
356+
provided, all lines will have the same length.
330357
331-
colors : array_like of colors, optional, default: 'k'
358+
colors : array-like of colors, optional, default: 'k'
332359
333360
linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional
334361
@@ -353,104 +380,137 @@ See the `~.Axes.hlines` documentation for how this renders.
353380
The Sphinx_ website also contains plenty of documentation_ concerning ReST
354381
markup and working with Sphinx in general.
355382

356-
.. note::
357-
358-
Some parts of the documentation do not yet conform to the current
359-
documentation style. If in doubt, follow the rules given here and not what
360-
you may see in the source code. Pull requests updating docstrings to
361-
the current style are very welcome.
362-
363383
Formatting conventions
364384
----------------------
365385

366-
The basic docstring conventions are covered in the `numpy documentation howto`_
386+
The basic docstring conventions are covered in the `numpydoc docstring guide`_
367387
and the Sphinx_ documentation. Some Matplotlib-specific formatting conventions
368388
to keep in mind:
369389

370-
* Matplotlib does not have a convention whether to use single-quotes or
371-
double-quotes. There is a mixture of both in the current code.
390+
Function arguments
391+
Function arguments and keywords within docstrings should be referred to
392+
using the ``*emphasis*`` role. This will keep Matplotlib's documentation
393+
consistent with Python's documentation:
372394

373-
* Long parameter lists should be wrapped using a ``\`` for continuation and
374-
starting on the new line without any indent:
395+
.. code-block:: rst
375396
376-
.. code-block:: python
397+
If *linestyles* is *None*, the 'solid' is used.
377398
378-
def add_axes(self, *args, **kwargs):
379-
"""
380-
...
399+
Do not use the ```default role``` or the ````literal```` role:
381400

382-
Parameters
383-
----------
384-
projection :
385-
{'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
386-
'rectilinear'}, optional
387-
The projection type of the axes.
401+
.. code-block:: rst
388402
389-
...
390-
"""
403+
Neither `argument` nor ``argument`` should be used.
391404
392-
Alternatively, you can describe the valid parameter values in a dedicated
393-
section of the docstring.
394405
395-
* Generally, do not add markup to types for ``Parameters`` and ``Returns``.
396-
This is usually not needed because Sphinx will link them automatically and
397-
would unnecessarily clutter the docstring. However, it does seem to fail in
398-
some situations. If you encounter such a case, you are allowed to add markup:
406+
Quotes for strings
407+
Matplotlib does not have a convention whether to use single-quotes or
408+
double-quotes. There is a mixture of both in the current code.
399409

400-
.. code-block:: rst
410+
Use simple single or double quotes when giving string values, e.g.:: rst
401411

402-
Returns
403-
-------
404-
lines : `~matplotlib.collections.LineCollection`
412+
.. code-block:: rst
405413
406-
* rcParams can be referenced with the custom ``:rc:`` role:
407-
:literal:`:rc:\`foo\`` yields ``rcParams["foo"]``.
414+
If 'tight', try to figure out the tight bbox of the figure.
408415
409-
Deprecated formatting conventions
410-
---------------------------------
411-
* Formerly, we have used square brackets for explicit parameter lists
412-
``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their
413-
standard using curly braces ``{'solid', 'dashed', 'dotted'}``.
416+
Parameter type descriptions
417+
The main goal for parameter type descriptions is to be readable and
418+
understandable by humans. If the possible types are too complex use a
419+
simplification for the type description and explain the type more
420+
precisely in the text.
414421

415-
Linking to other code
416-
---------------------
417-
To link to other methods, classes, or modules in Matplotlib you can encase
418-
the name to refer to in back ticks, for example:
422+
Generally, the `numpydoc docstring guide`_ conventions apply. The following
423+
rules expand on them where the numpydoc conventions are not specific.
419424

420-
.. code-block:: python
425+
Use ``float`` for a type that can be any number.
421426

422-
`~matplotlib.collections.LineCollection`
427+
Use ``array-like`` for homogeneous numeric sequences, which could
428+
typically be a numpy.array. Dimensionality may be specified using ``2D``,
429+
``3D``, ``n-dimensional``. If you need to have variables denoting the
430+
sizes of the dimensions, use capital letters in brackets
431+
(``array-like (M, N)``). When refering to them in the text they are easier
432+
read and no special formatting is needed.
423433

424-
It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.
425-
Sometimes it is tricky to get external Sphinx linking to work; to check that
426-
a something exists to link to the following shell command outputs a list of all
427-
objects that can be referenced (in this case for Numpy)::
434+
``float`` is the implicit default dtype for array-likes. For other dtypes
435+
use ``array-like of int``.
428436

429-
python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv'
437+
Some possible uses::
430438

439+
2D array-like
440+
array-like (N)
441+
array-like (M, N)
442+
array-like (M, N, 3)
443+
array-like of int
431444

432-
Function arguments
433-
------------------
434-
Function arguments and keywords within docstrings should be referred to using
435-
the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
436-
with Python's documentation:
445+
Non-numeric homogeneous sequences are described as lists, e.g.::
437446

438-
.. code-block:: rst
447+
list of str
448+
list of `.Artist`
439449

440-
Here is a description of *argument*
450+
Referencing types
451+
Generally, the rules from referring-to-other-code_ apply. More specifically:
441452

442-
Do not use the ```default role```:
453+
Use full references ```~matplotlib.colors.Normalize``` with an
454+
abbreviation tilde in parameter types. While the full name helps the
455+
reader of plain text docstrings, the HTML does not need to show the full
456+
name as it links to it. Hence, the ``~``-shortening keeps it more readable.
443457

458+
Use abbreviated links ```.Normalize``` in the text.
444459

445-
.. code-block:: rst
460+
.. code-block:: rst
446461
447-
Do not describe `argument` like this.
462+
norm : `~matplotlib.colors.Normalize`, optional
463+
A `.Normalize` instance is used to scale luminance data to 0, 1.
448464
449-
nor the ````literal```` role:
465+
``See also`` sections
466+
Sphinx automatically links code elements in the definition blocks of ``See
467+
also`` sections. No need to use backticks there::
450468

451-
.. code-block:: rst
469+
See also
470+
--------
471+
vlines : vertical lines
472+
axhline: horizontal line across the axes
452473

453-
Do not describe ``argument`` like this.
474+
Wrapping parameter lists
475+
Long parameter lists should be wrapped using a ``\`` for continuation and
476+
starting on the new line without any indent:
477+
478+
.. code-block:: python
479+
480+
def add_axes(self, *args, **kwargs):
481+
"""
482+
...
483+
484+
Parameters
485+
----------
486+
projection :
487+
{'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
488+
'rectilinear'}, optional
489+
The projection type of the axes.
490+
491+
...
492+
"""
493+
494+
Alternatively, you can describe the valid parameter values in a dedicated
495+
section of the docstring.
496+
497+
rcParams
498+
rcParams can be referenced with the custom ``:rc:`` role:
499+
:literal:`:rc:\`foo\`` yields ``rcParams["foo"]``. Use `= [default-val]`
500+
to indicate the default value of the parameter. The default value should be
501+
literal, i.e. enclosed in double backticks. For simplicity these may be
502+
omitted for string default values.
503+
504+
.. code-block:: rst
505+
506+
If not provided, defaults to :rc:`figure.figsize` = ``[6.4, 4.8]``.
507+
If not provided, defaults to :rc:`figure.facecolor` = 'w'.
508+
509+
Deprecated formatting conventions
510+
---------------------------------
511+
Formerly, we have used square brackets for explicit parameter lists
512+
``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their
513+
standard using curly braces ``{'solid', 'dashed', 'dotted'}``.
454514

455515
Setters and getters
456516
-------------------
@@ -461,6 +521,12 @@ By convention, these setters and getters are named ``set_PROPERTYNAME`` and
461521
``get_PROPERTYNAME``; the list of properties thusly defined on an artist and
462522
their values can be listed by the `~.pyplot.setp` and `~.pyplot.getp` functions.
463523

524+
.. note::
525+
526+
``ACCEPTS`` blocks have recently become optional. You may now use a
527+
numpydoc ``Parameters`` block because the accepted values can now be read
528+
from the type description of the first parameter.
529+
464530
Property setter methods should indicate the values they accept using a (legacy)
465531
special block in the docstring, starting with ``ACCEPTS``, as follows:
466532

@@ -494,7 +560,6 @@ Sphinx by making it a ReST comment (i.e. use ``.. ACCEPTS:``):
494560
"""
495561
496562
497-
498563
Keyword arguments
499564
-----------------
500565

@@ -791,4 +856,4 @@ Some helpful functions::
791856
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
792857
.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
793858
.. _references: http://www.sphinx-doc.org/en/stable/markup/inline.html
794-
.. _`numpy documentation howto`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
859+
.. _`numpydoc docstring guide`: https://numpydoc.readthedocs.io/en/latest/format.html

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.