DOC: Improve module docs of matplotlib.scale

timhoffm · timhoffm · commit 46e326d510a0 · 2024-12-20T09:24:42.000+01:00
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -1,8 +1,27 @@
 """
 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.
+
+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 scales examples in the documentation.
 
 See :doc:`/gallery/scales/custom_scale` for a full example of defining a custom
 scale.
@@ -412,6 +431,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
