Restructure API Reference index page

doc/api/axes_api.rst

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

doc/api/index.rst

@@ -36,35 +36,60 @@ 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:
 
+- 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 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:: 2
 
-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:: ``Axes`` interface
 
-Further reading:
+        API:
+
+        - `~matplotlib.figure.Figure`: configure all figure related settings
+        - :ref:`Axes <matplotlib-axes>`: add data, configure limits, set labels etc.
+
+        Examples:
+
+        - Most of the :ref:`examples <examples-index>` use this
+          (except for the pyplot section)
+
+    .. grid-item-card:: ``pyplot`` interface
+
+        API:
+
+        - `matplotlib.pyplot` function reference
+
+        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:
 
-- `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)
 
 
-The implicit API
-^^^^^^^^^^^^^^^^
+The pyplot interface
+^^^^^^^^^^^^^^^^^^^^
 
-`matplotlib.pyplot` is a collection of functions that make
+`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.
@@ -74,9 +99,6 @@ programmatic plot generation.
 
 Further reading:
 
-- The `matplotlib.pyplot` function reference
-- :ref:`pyplot_tutorial`
-- :ref:`Pyplot examples <pyplots_examples>`
 
 .. _api-index: