Improve matplotlib.axes documentation

timhoffm · story645 · timhoffm · commit dbad2d1c33ec · 2022-12-19T21:02:34.000+01:00
- Move the Axes class documentation to a sub-page.
  The constructor is quite lengthy and not needed by
  most users.
- Add an introductory sentence to set the context for the
  subsequent listing and structure of the Axes methods.

Note: I've removed the inheritance diagram, because it
does not contain much relevant information.
The inheritance from _AxesBase is shown in the class
docstring as well. The only additional information is
that it originally inherits from Artist, which I've
now included as a sentence in the docstring.

Co-authored-by: hannah &lt;story645@gmail.com&gt;
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -2,6 +2,10 @@
 ``matplotlib.axes``
 *******************
 
+The `~.axes.Axes` class represents one (sub-)plot in a figure. It contains the
+plotted, data axis ticks, labels, title, legend, etc. Its methods are the main
+interface for manipulating the plot.
+
 .. currentmodule:: matplotlib.axes
 
 .. contents:: Table of Contents
@@ -14,18 +18,15 @@
    :no-members:
    :no-undoc-members:
 
-Inheritance
-===========
-.. inheritance-diagram:: matplotlib.axes.Axes
-   :private-bases:
-
 The Axes class
 ==============
 
-.. autoclass:: Axes
-   :no-members:
-   :no-undoc-members:
-   :show-inheritance:
+.. autosummary::
+   :toctree: _as_gen
+   :template: autosummary.rst
+   :nosignatures:
+
+   Axes
 
 Plotting
 ========
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -46,10 +46,15 @@
 @_docstring.interpd
 class Axes(_AxesBase):
     """
-    The `Axes` contains most of the figure elements: `~.axis.Axis`,
+    An Axes object encapsulates all the elements of an individual (sub-)plot in
+    a figure.
+
+    It contains most of the (sub-)plot elements: `~.axis.Axis`,
     `~.axis.Tick`, `~.lines.Line2D`, `~.text.Text`, `~.patches.Polygon`, etc.,
     and sets the coordinate system.
 
+    Like all visible elements in a figure, Axes is an `.Artist` subclass.
+
     The `Axes` instance supports callbacks through a callbacks attribute which
     is a `~.cbook.CallbackRegistry` instance.  The events you can connect to
     are 'xlim_changed' and 'ylim_changed' and the callback will be called with
