DOC: Improve autoscaling and margin docs

Author: timhoffm

galleries/users_explain/axes/autoscale.py

@@ -6,33 +6,40 @@
 Axis autoscaling
 ================
 
-The limits on an axis can be set manually (e.g. ``ax.set_xlim(xmin, xmax)``)
-or Matplotlib can set them automatically based on the data already on the Axes.
-There are a number of options to this autoscaling behaviour, discussed below.
-"""
+Basic concept
+-------------
 
-# %%
-# We will start with a simple line plot showing that autoscaling
-# extends the axis limits 5% beyond the data limits (-2π, 2π).
+Autoscaling ensures that data is visible within the Axes by automatically adjusting the axis limits.
+When you plot data, Matplotlib's autoscaling mechanism updates the axis limits accordingly.
+"""
 
 import matplotlib.pyplot as plt
 import numpy as np
 
 
-x = np.linspace(-2 * np.pi, 2 * np.pi, 100)
+x = np.linspace(-6, 6, 201)
 y = np.sinc(x)
 
 fig, ax = plt.subplots()
 ax.plot(x, y)
 
 # %%
+#
+# .. _autoscale_margins:
+#
 # Margins
 # -------
-# The default margin around the data limits is 5%, which is based on the
-# default configuration setting of :rc:`axes.xmargin`, :rc:`axes.ymargin`,
-# and :rc:`axes.zmargin`:
+# To ensure that the data is not at the very edge of the plot, Matplotlib adds a
+# margin around the data limits. Note that the *x* data range in the above plot is
+# [-6, 6], but the x-axis limits are slightly wider due to the default margin.
+#
+# The default margin around the data limits is 5%, defined via
+# 
+# - :rc:`axes.xmargin`
+# - :rc:`axes.ymargin`
+# - :rc:`axes.zmargin`
 
-print(ax.margins())
+print(ax.get_xmargin(), ax.get_ymargin())
 
 # %%
 # The margin size can be overridden to make them smaller or larger using
@@ -116,14 +123,14 @@
 ax[1].set_title("Two curves")
 
 # %%
-# However, there are cases when you don't want to automatically adjust the
-# viewport to new data.
+# If you don't want automatic updates of the axis limies, either deactivate
+# autoscaling with `~.axes.Axes.autoscale` or set the limits
+# manually with `~.axes.Axes.set_xlim` / `~.axes.Axes.set_ylim`.
 #
-# One way to disable autoscaling is to manually set the
-# axis limit. Let's say that we want to see only a part of the data in
+# Let's say that we want to see only a part of the data in
 # greater detail. Setting the ``xlim`` persists even if we add more curves to
-# the data. To recalculate the new limits  calling `.Axes.autoscale` will
-# toggle the functionality manually.
+# the data. Calling `.Axes.autoscale` will again re-enable the autoscaling and
+# recalculate the limits to fit all the data.
 
 fig, ax = plt.subplots(ncols=2, figsize=(12, 8))
 ax[0].plot(x, y)

lib/matplotlib/axes/_base.py

@@ -2787,6 +2787,13 @@ def set_autoscale_on(self, b):
         Parameters
         ----------
         b : bool
+
+        See Also
+        --------
+        :ref:`autoscale`
+        matplotlib.axes.Axes.autoscale
+        matplotlib.axes.Axes.set_autoscalex_on
+        matplotlib.axes.Axes.set_autoscaley_on
         """
         for axis in self._axis_map.values():
             axis._set_autoscale_on(b)
@@ -2825,6 +2832,7 @@ def get_xmargin(self):
 
         See Also
         --------
+        :ref:`autoscale_margins`
         matplotlib.axes.Axes.set_xmargin
         """
         return self._xmargin
@@ -2841,6 +2849,7 @@ def get_ymargin(self):
 
         See Also
         --------
+        :ref:`autoscale_margins`
         matplotlib.axes.Axes.set_ymargin
         """
         return self._ymargin
@@ -2860,6 +2869,13 @@ def set_xmargin(self, m):
         Parameters
         ----------
         m : float greater than -0.5
+
+        See Also
+        --------
+        :ref:`autoscale_margins`
+        matplotlib.axes.Axes.margins
+        matplotlib.axes.Axes.get_xmargin
+
         """
         if m <= -0.5:
             raise ValueError("margin must be greater than -0.5")
@@ -2882,6 +2898,12 @@ def set_ymargin(self, m):
         Parameters
         ----------
         m : float greater than -0.5
+
+        See Also
+        --------
+        :ref:`autoscale_margins`
+        matplotlib.axes.Axes.margins
+        matplotlib.axes.Axes.get_ymargin
         """
         if m <= -0.5:
             raise ValueError("margin must be greater than -0.5")
@@ -2945,6 +2967,7 @@ def margins(self, *margins, x=None, y=None, tight=True):
 
         See Also
         --------
+        :ref:`autoscale_margins`
         .Axes.set_xmargin, .Axes.set_ymargin
         """
 
@@ -2999,10 +3022,12 @@ def autoscale(self, enable=True, axis='both', tight=None):
         """
         Autoscale the axis view to the data (toggle).
 
-        Convenience method for simple axis view autoscaling.
-        It turns autoscaling on or off, and then,
-        if autoscaling for either axis is on, it performs
-        the autoscaling on the specified axis or Axes.
+        Convenience method for simple axis view autoscaling. This does:
+        
+        - Turn autoscaling on or off (`~.axes.Axes.set_autoscalex_on` /
+          `~.axes.Axes.set_autoscaley_on`).
+        - Ensure that view limits will get updated when needed. - As view limits
+          are lazy-updated, this technically marks the view limits as stale.
 
         Parameters
         ----------
@@ -3016,6 +3041,13 @@ def autoscale(self, enable=True, axis='both', tight=None):
             If True, first set the margins to zero.  Then, this argument is
             forwarded to `~.axes.Axes.autoscale_view` (regardless of
             its value); see the description of its behavior there.
+
+        See Also
+        --------
+        :ref:`autoscale`
+        matplotlib.axes.Axes.set_autoscale_on
+        matplotlib.axes.Axes.set_autoscalex_on
+        matplotlib.axes.Axes.set_autoscaley_on
         """
         if enable is None:
             scalex = True
@@ -3065,7 +3097,7 @@ def autoscale_view(self, tight=None, scalex=True, scaley=True):
 
         scaley : bool, default: True
             Whether to autoscale the y-axis.
-
+           
         Notes
         -----
         The autoscaling preserves any preexisting axis direction reversal.

lib/matplotlib/axis.py

@@ -838,6 +838,15 @@ def _set_autoscale_on(self, b):
         Parameters
         ----------
         b : bool
+
+        See Also
+        --------
+        matplotlib.axes.Axes.autoscale
+        matplotlib.axes.Axes.set_autoscale_on
+        matplotlib.axes.Axes.get_autoscalex_on
+        matplotlib.axes.Axes.set_autoscalex_on
+        matplotlib.axes.Axes.get_autoscaley_on
+        matplotlib.axes.Axes.set_autoscaley_on
         """
         if b is not None:
             self._autoscale_on = b