Restructure interface section 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.

Author: timhoffm

doc/api/axes_api.rst

@@ -1,5 +1,3 @@
-.. _matplotlib-axes:
-
 *******************
 ``matplotlib.axes``
 *******************

doc/api/index.rst

@@ -41,65 +41,47 @@ Matplotlib provides two different interfaces:
 - Within the *Axes interface* you create a Figure and one or more Axes objects
   (typically using `.pyplot.subplots`). Then, you use methods on these objects to add
   data, configure limits, set labels etc.
-- The *pyplot interface* consists of functions that make changes
+- The *pyplot interface* consists of functions. Figure and Axes are manipulated through
+  these functions and are only implicitly present in the background.
 
 See :ref:`api_interfaces` for a more detailed description of both and their recommended
 use cases.
 
-.. grid:: 2
+.. grid:: 1 1 2 2
+    :padding: 0 0 1 1
 
-    .. grid-item-card:: ``Axes`` interface
+    .. grid-item-card::
+
+        **Axes interface** (object-based, explicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
         API:
 
-        - `~matplotlib.figure.Figure`: configure all figure related settings
-        - :ref:`Axes <matplotlib-axes>`: add data, configure limits, set labels etc.
+        - `~.pyplot.subplots`: create Figure and Axes
+        - :doc:`Axes </api/axes_api>` add data, limits, labels etc.
+        - :doc:`Figure <figure_api>` for figure-level methods
 
         Examples:
 
-        - Most of the :ref:`examples <examples-index>` use this
+        - Most :ref:`examples <examples-index>` use this
+
           (except for the pyplot section)
 
-    .. grid-item-card:: ``pyplot`` interface
+    .. grid-item-card::
+
+        **pyplot interface** (function-based, implicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
         API:
 
-        - `matplotlib.pyplot` function reference
+        - `matplotlib.pyplot`
 
         Examples:
 
         - :ref:`pyplot_tutorial`
         - :ref:`Pyplot examples <pyplots_examples>`
 
 
-The Axes interface
-^^^^^^^^^^^^^^^^^^
-
-Typically, you will use `.pyplot.subplots` to create a `.Figure` and one or more
-`~matplotlib.axes.Axes` objects. From then on, you will use methods on these objects
-to add data, configure limits, set labels etc.
-
-Relevant API:
-
-
-Examples:
-
-
-
-The pyplot interface
-^^^^^^^^^^^^^^^^^^^^
-
-`matplotlib.pyplot` is function based interface.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` is mainly intended for interactive plots and simple cases of
-programmatic plot generation.
-
-Further reading:
-
-
 .. _api-index:
 
 Modules

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.