Skip to content

Commit f7dcf3f

Browse files
committed
Restructure interface section of API Reference index page
- switch to Axes interface / pyplot interface terminology (matplotlib#26388) - Reduce the interface description to very compact two-sentence descriptions and refer to the interface page for everything else. The focus here is to point the users to relevant API resources for the respective interfaces, not to discuss these interfaces in detail. The latter is the task of https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html and I will add some missing pieces there in a follow-up PR.
1 parent c12be12 commit f7dcf3f

2 files changed

Lines changed: 35 additions & 31 deletions

File tree

‎doc/api/index.rst‎

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -36,47 +36,51 @@ methods on them to plot data, add axis labels and a figure title.
3636
Usage patterns
3737
--------------
3838

39-
Below we describe several common approaches to plotting with Matplotlib. See
40-
:ref:`api_interfaces` for an explanation of the trade-offs between the supported user
41-
APIs.
39+
Matplotlib provides two different interfaces:
4240

41+
- Within the *Axes interface* you create a Figure and one or more Axes objects
42+
(typically using `.pyplot.subplots`). Then, you use methods on these objects to add
43+
data, configure limits, set labels etc.
44+
- The *pyplot interface* consists of functions. Figure and Axes are manipulated through
45+
these functions and are only implicitly present in the background.
4346

44-
The explicit API
45-
^^^^^^^^^^^^^^^^
47+
See :ref:`api_interfaces` for a more detailed description of both and their recommended
48+
use cases.
4649

47-
At its core, Matplotlib is an object-oriented library. We recommend directly
48-
working with the objects if you need more control and customization of your
49-
plots.
50+
.. grid:: 1 1 2 2
51+
:padding: 0 0 1 1
5052

51-
In many cases you will create a `.Figure` and one or more
52-
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
53-
on these objects. However, it's also possible to create `.Figure`\ s
54-
explicitly (e.g. when including them in GUI applications).
53+
.. grid-item-card::
5554

56-
Further reading:
55+
**Axes interface** (object-based, explicit)
56+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5757

58-
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
59-
plotting functions.
60-
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
61-
(except for the pyplot section)
58+
API:
6259

60+
- `~.pyplot.subplots`: create Figure and Axes
61+
- :doc:`Axes </api/axes_api>` add data, limits, labels etc.
62+
- :doc:`Figure <figure_api>` for figure-level methods
6363

64-
The implicit API
65-
^^^^^^^^^^^^^^^^
64+
Examples:
6665

67-
`matplotlib.pyplot` is a collection of functions that make
68-
Matplotlib work like MATLAB. Each pyplot function makes some change to a
69-
figure: e.g., creates a figure, creates a plotting area in a figure, plots
70-
some lines in a plotting area, decorates the plot with labels, etc.
66+
- Most :ref:`examples <examples-index>` use this
7167

72-
`.pyplot` is mainly intended for interactive plots and simple cases of
73-
programmatic plot generation.
68+
(except for the pyplot section)
7469

75-
Further reading:
70+
.. grid-item-card::
71+
72+
**pyplot interface** (function-based, implicit)
73+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
74+
75+
API:
76+
77+
- `matplotlib.pyplot`
78+
79+
Examples:
80+
81+
- :ref:`pyplot_tutorial`
82+
- :ref:`Pyplot examples <pyplots_examples>`
7683

77-
- The `matplotlib.pyplot` function reference
78-
- :ref:`pyplot_tutorial`
79-
- :ref:`Pyplot examples <pyplots_examples>`
8084

8185
.. _api-index:
8286

‎lib/matplotlib/pylab.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""
22
`pylab` is a historic interface and its use is strongly discouraged. The equivalent
3-
replacement is `matplotlib.pyplot`. See :ref:` api_interfaces` for a full overview
3+
replacement is `matplotlib.pyplot`. See :ref:`api_interfaces` for a full overview
44
of Matplotlib interfaces.
55
66
`pylab` was designed to support a MATLAB-like way of working with all plotting related
@@ -14,7 +14,7 @@
1414
`numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into
1515
the global namespace.
1616
17-
Such a pattern is nowadays considered bad practice, as it clutters the global
17+
Such a pattern is considered bad practice in modern python, as it clutters the global
1818
namespace. Even more severely, in the case of `pylab`, this will overwrite some
1919
builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which
2020
can lead to unexpected behavior.

0 commit comments

Comments
 (0)