Backport PR #29404: DOC: scales - built in options and custom scale usefulness

timhoffm · meeseeksmachine · commit bed828125937 · 2025-01-11T23:26:08.000Z
diff --git a/galleries/examples/scales/custom_scale.py b/galleries/examples/scales/custom_scale.py
@@ -5,13 +5,25 @@
 Custom scale
 ============
 
-Create a custom scale, by implementing the scaling use for latitude data in a
-Mercator Projection.
+Custom scales can be created in two ways
+
+#. For simple cases, use `~.scale.FuncScale` and the ``'function'`` option of
+   `~.Axes.set_xscale` and `~.Axes.set_yscale`.  See the last example in
+   :doc:`/gallery/scales/scales`.
+
+#. Create a custom scale class such as the one in this example, which implements
+   the scaling use for latitude data in a Mercator Projection.  This more complicated
+   approach is useful when
+
+   * You are making special use of the `.Transform` class, such as the special
+     handling of values beyond the threshold in ``MercatorLatitudeTransform``
+     below.
+
+   * You want to override the default locators and formatters for the axis
+     (``set_default_locators_and_formatters`` below).
+
+   * You want to limit the range of the the axis (``limit_range_for_scale`` below).
 
-Unless you are making special use of the `.Transform` class, you probably
-don't need to use this verbose method, and instead can use `~.scale.FuncScale`
-and the ``'function'`` option of `~.Axes.set_xscale` and `~.Axes.set_yscale`.
-See the last example in :doc:`/gallery/scales/scales`.
 """
 
 import numpy as np
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -777,26 +777,15 @@ def _set_axes_scale(self, value, **kwargs):
 
         Parameters
         ----------
-        value : {"linear", "log", "symlog", "logit", ...} or `.ScaleBase`
-            The axis scale type to apply.
+        value : str or `.ScaleBase`
+            The axis scale type to apply.  Valid string values are the names of scale
+            classes ("linear", "log", "function",...).  These may be the names of any
+            of the :ref:`built-in scales<builtin_scales>` or of any custom scales
+            registered using `matplotlib.scale.register_scale`.
 
         **kwargs
-            Different keyword arguments are accepted, depending on the scale.
-            See the respective class keyword arguments:
-
-            - `matplotlib.scale.LinearScale`
-            - `matplotlib.scale.LogScale`
-            - `matplotlib.scale.SymmetricalLogScale`
-            - `matplotlib.scale.LogitScale`
-            - `matplotlib.scale.FuncScale`
-            - `matplotlib.scale.AsinhScale`
-
-        Notes
-        -----
-        By default, Matplotlib supports the above-mentioned scales.
-        Additionally, custom scales may be registered using
-        `matplotlib.scale.register_scale`. These scales can then also
-        be used here.
+            If *value* is a string, keywords are passed to the instantiation method of
+            the respective class.
         """
         name = self._get_axis_name()
         old_default_lims = (self.get_major_locator()
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -3,7 +3,9 @@
 
 The mapping is implemented through `.Transform` subclasses.
 
-The following scales are builtin:
+The following scales are built-in:
+
+.. _builtin_scales:
 
 ============= ===================== ================================ =================================
 Name          Class                 Transform                        Inverted transform
