DOC: Improve module docs of matplotlib.scale

timhoffm · timhoffm · commit fe238dad0b87 · 2024-12-20T11:40:10.000+01:00
diff --git a/doc/api/scale_api.rst b/doc/api/scale_api.rst
@@ -6,3 +6,4 @@
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -1,16 +1,36 @@
 """
 Scales define the distribution of data values on an axis, e.g. a log scaling.
-They are defined as subclasses of `ScaleBase`.
 
-See also `.axes.Axes.set_xscale` and the scales examples in the documentation.
+Scales are subclasses `ScaleBase`. Their mapping is implemented through `.Transform`
+subclasses that are separable and have an inverse.
 
-See :doc:`/gallery/scales/custom_scale` for a full example of defining a custom
-scale.
+The following scales are builtin:
+
+============= ===================== ================================ =================================
+Name          Class                 Transform                        Inverted transform
+============= ===================== ================================ =================================
+"asinh"       `AsinhScale`          `AsinhTransform`                 `InvertedAsinhTransform`
+"function"    `FuncScale`           `FuncTransform`                  `FuncTransform`
+"functionlog" `FuncScaleLog`        `FuncTransform` + `LogTransform` `InvertedLogTransform` + `FuncTransform`
+"linear"      `LinearScale`         `.IdentityTransform`             `.IdentityTransform`
+"log"         `LogScale`            `LogTransform`                   `InvertedLogTransform`
+"logit"       `LogitScale`          `LogitTransform`                 `LogisticTransform`
+"symlog"      `SymmetricalLogScale` `SymmetricalLogTransform`        `InvertedSymmetricalLogTransform`
+============= ===================== ================================ =================================
+
+A user will often only use the scale name, e.g. when setting the scale through
+`~.Axes.set_xscale`: ``ax.set_xscale("log")``.
+
+See also the :ref:`scales examples <sphx_glr_gallery_scales>` in the documentation.
+
+Custom scaling can be achieved through `FuncScale`, or by creating your own
+`ScaleBase` subclass (see :doc:`/gallery/scales/custom_scale`).
+Third parties can register their scales by name through `register_scale`.
 
 Matplotlib also supports non-separable transformations that operate on both
-`~.axis.Axis` at the same time.  They are known as projections, and defined in
+`~.axis.Axis` at the same time.  They are known as *projections*, and defined in
 `matplotlib.projections`.
-"""
+"""  # noqa: E501
 
 import inspect
 import textwrap
@@ -412,6 +432,8 @@ class SymmetricalLogScale(ScaleBase):
     *linthresh* allows the user to specify the size of this range
     (-*linthresh*, *linthresh*).
 
+    See :doc:`/gallery/scales/symlog_demo` for a detailed description.
+
     Parameters
     ----------
     base : float, default: 10
