[DOC] Enhance API reference index

timhoffm · timhoffm · commit 03d16a42378e · 2023-08-31T00:42:29.000+02:00
diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css
@@ -122,6 +122,11 @@ table.property-table td {
     margin: 0 0.5em;
 }
 
+/* Make the code examples in the API reference index the same height. */
+.api-interface-example pre {
+    min-height: 6.5rem;
+}
+
 /* Make inheritance images have a scroll bar if necessary. */
 div.graphviz {
     border: 1px solid lightgrey;
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -4,41 +4,74 @@ API Reference
 Matplotlib interfaces
 ---------------------
 
-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.
-
-See :ref:`api_interfaces` for a more detailed description of both and their recommended
-use cases.
+.. |nbsp| unicode:: 0xA0
+   :trim:
 
 .. grid:: 1 1 2 2
-    :padding: 0 0 1 1
+    :padding: 0
+    :gutter: 2
 
     .. grid-item-card::
+        :class-footer: api-interface-footer
 
         **Axes interface** (object-based, explicit)
-        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+        create a `.Figure` and one or more `~.axes.Axes` objects, then *explicitly* use
+        methods on these objects to add data, configure limits, set labels etc.
+
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
         API:
 
         - `~.pyplot.subplots`: create Figure and Axes
         - :mod:`~matplotlib.axes`: add data, limits, labels etc.
         - `.Figure`: for figure-level methods
 
+        +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+        Example:
+
+        .. code-block:: python
+           :class: api-interface-example
+
+           fig, ax = plt.subplots()
+           ax.plot(x, y)
+           ax.set_title("Sample plot")
+           plt.show()
+
+        :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
     .. grid-item-card::
+        :class-footer: api-interface-footer
 
         **pyplot interface** (function-based, implicit)
-        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+        consists of functions in the `.pyplot` module. Figure and Axes are manipulated
+        through these functions and are only *implicitly* present in the background.
+
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
         API:
 
         - `matplotlib.pyplot`
 
+        +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+        Example:
+
+        .. code-block:: python
+           :class: api-interface-example
+
+           plt.plot(x, y)
+           plt.title("Sample plot")
+           plt.show()
+
+        :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+See :ref:`api_interfaces` for a more detailed description of both and their recommended
+use cases.
+
 
 .. _api-index:
 
