Restructure interface section of API Reference index page

timhoffm · timhoffm · commit e272b5c4f84b · 2023-07-29T01:19:43.000+02:00
- switch to Axes interface / pyplot interface terminology (#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. Co-authored-by: hannah <story645@gmail.com>
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -36,47 +36,41 @@ methods on them to plot data, add axis labels and a figure title.
 Usage patterns
 --------------
 
-Below we describe several common approaches to plotting with Matplotlib.  See
-:ref:`api_interfaces` for an explanation of the trade-offs between the supported user
-APIs.
+Matplotlib provides two different interfaces:
 
+- **Axes interface**: create a `.Figure` and one or more `~.axes.Axes` objects
+  (typically using `.pyplot.subplots`), then *explicitly* use methods on these objects
+  to add data, configure limits, set labels etc.
+- **pyplot interface**: consists of functions in the `.pyplot` module. Figure and Axes
+  are manipulated through these functions and are only *implicitly* present in the
+  background.
 
-The explicit API
-^^^^^^^^^^^^^^^^
+See :ref:`api_interfaces` for a more detailed description of both and their recommended
+use cases.
 
-At its core, Matplotlib is an object-oriented library. We recommend directly
-working with the objects if you need more control and customization of your
-plots.
+.. grid:: 1 1 2 2
+    :padding: 0 0 1 1
 
-In many cases you will create a `.Figure` and one or more
-`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
-on these objects. However, it's also possible to create `.Figure`\ s
-explicitly (e.g. when including them in GUI applications).
+    .. grid-item-card::
 
-Further reading:
+        **Axes interface** (object-based, explicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
-  plotting functions.
-- Most of the :ref:`examples <examples-index>` use the object-oriented approach
-  (except for the pyplot section)
+        API:
 
+        - `~.pyplot.subplots`: create Figure and Axes
+        - :doc:`Axes </api/axes_api>` add data, limits, labels etc.
+        - :doc:`Figure <figure_api>` for figure-level methods
 
-The implicit API
-^^^^^^^^^^^^^^^^
+    .. grid-item-card::
 
-`matplotlib.pyplot` is a collection of functions that make
-Matplotlib work like MATLAB. Each pyplot function makes some change to a
-figure: e.g., creates a figure, creates a plotting area in a figure, plots
-some lines in a plotting area, decorates the plot with labels, etc.
+        **pyplot interface** (function-based, implicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-`.pyplot` is mainly intended for interactive plots and simple cases of
-programmatic plot generation.
+        API:
 
-Further reading:
+        - `matplotlib.pyplot`
 
-- The `matplotlib.pyplot` function reference
-- :ref:`pyplot_tutorial`
-- :ref:`Pyplot examples <pyplots_examples>`
 
 .. _api-index:
 
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
@@ -1,6 +1,6 @@
 """
 `pylab` is a historic interface and its use is strongly discouraged. The equivalent
-replacement is `matplotlib.pyplot`.  See :ref:` api_interfaces` for a full overview
+replacement is `matplotlib.pyplot`.  See :ref:`api_interfaces` for a full overview
 of Matplotlib interfaces.
 
 `pylab` was designed to support a MATLAB-like way of working with all plotting related
@@ -14,7 +14,7 @@
    `numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into
    the global namespace.
 
-   Such a pattern is nowadays considered bad practice, as it clutters the global
+   Such a pattern is considered bad practice in modern python, as it clutters the global
    namespace. Even more severely, in the case of `pylab`, this will overwrite some
    builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which
    can lead to unexpected behavior.
