DOC: simplify API index

jklymak · jklymak · commit 271687056982 · 2021-03-17T14:57:01.000-07:00
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -1,3 +1,5 @@
+.. _axes_api 
+
 *******************
 ``matplotlib.axes``
 *******************
diff --git a/doc/api/figure_api.rst b/doc/api/figure_api.rst
@@ -1,3 +1,5 @@
+.. _figure_api
+
 *********************
 ``matplotlib.figure``
 *********************
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -1,67 +1,39 @@
-API Overview
-============
+API
+===
 
-.. toctree::
-   :hidden:
+For recent changes, see :doc:`api_changes`.
 
-   api_changes
+Much of the library can be accessed by creating :doc:`Figure <figure_api>` 
+and :doc:`Axes <axes_api>` objects and accessing methods on them. 
 
-.. contents:: :local:
+  - :doc:`figure_api`: axes creation, figure-level artists
+  - :doc:`axes_api`: most plotting methods, axes labels, access to 
+    axis styling, etc.  
 
-See also the :doc:`api_changes`.
+Simple example: note how the ``ax`` object has the `.axes.Axes.plot` method 
+that is used to create the line plot. 
+ 
+.. plot::
+   :include-source:
+   :align: center
 
-Usage patterns
---------------
+   import matplotlib.pyplot as plt
+   import numpy as np
 
-Below we describe several common approaches to plotting with Matplotlib.
+   x = np.arange(0, 4, 0.1)
+   y = np.sin(x*np.pi)
 
-The pyplot API
-^^^^^^^^^^^^^^
+   fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True)
+   ax.plot(x, y)
+   ax.set_xlabel('t [s]')
+   ax.set_ylabel('S [V]')
+   fig.suptitle('Sine wave')
 
-`matplotlib.pyplot` is a collection of command style 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:
-
-- The `matplotlib.pyplot` function reference
-- :doc:`/tutorials/introductory/pyplot`
-- :ref:`Pyplot examples <pyplots_examples>`
-
-.. _api-index:
-
-The object-oriented API
-^^^^^^^^^^^^^^^^^^^^^^^
-
-At its core, Matplotlib is object-oriented. We recommend directly working
-with the objects, if you need more control and customization of your plots.
-
-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).
-
-Further reading:
-
-- `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 pylab API (disapproved)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: pylab
-   :no-members:
 
 Modules
 -------
 
-Matplotlib consists of the following submodules:
+Alphabetical list of all submodules:
 
 .. toctree::
    :maxdepth: 1
@@ -147,3 +119,52 @@ Matplotlib. The following toolkits are included:
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst
    toolkits/axes_grid.rst
+
+   
+Usage patterns
+--------------
+
+Below we describe several common approaches to plotting with Matplotlib.
+
+The pyplot API
+^^^^^^^^^^^^^^
+
+`matplotlib.pyplot` is a collection of command style 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:
+
+- The `matplotlib.pyplot` function reference
+- :doc:`/tutorials/introductory/pyplot`
+- :ref:`Pyplot examples <pyplots_examples>`
+
+.. _api-index:
+
+The object-oriented API
+^^^^^^^^^^^^^^^^^^^^^^^
+
+At its core, Matplotlib is object-oriented. We recommend directly working
+with the objects, if you need more control and customization of your plots.
+
+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).
+
+Further reading:
+
+- `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 pylab API (disapproved)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: pylab
+   :no-members:

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _axes_api`
	`2`	`+`
`1`	`3`	`*******************`
`2`	`4`	``matplotlib.axes``
`3`	`5`	`*******************`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _figure_api`
	`2`	`+`
`1`	`3`	`*********************`
`2`	`4`	``matplotlib.figure``
`3`	`5`	`*********************`