Merge pull request matplotlib#24769 from timhoffm/doc-axes-class

Improve matplotlib.axes documentation

Author: tacaswell

doc/_templates/autosummary_class_only.rst

@@ -0,0 +1,11 @@
+{{ fullname | escape | underline }}
+
+
+.. currentmodule:: {{ module }}
+
+
+{% if objtype in ['class'] %}
+.. auto{{ objtype }}:: {{ objname }}
+    :no-members:
+
+{% endif %}

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_class_only.rst
+   :nosignatures:
+
+   Axes
 
 Plotting
 ========

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