Use docstring interpolation instead.

anntzer · anntzer · commit 97fafd1eb0cf · 2022-06-23T12:10:21.000+02:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4320,6 +4320,7 @@ def invalid_shape_exception(csize, xsize):
                                      "edgecolors", "c", "facecolor",
                                      "facecolors", "color"],
                       label_namer="y")
+    @_docstring.interpd
     def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
                 vmin=None, vmax=None, alpha=None, linewidths=None, *,
                 edgecolors=None, plotnonfinite=False, **kwargs):
@@ -4366,10 +4367,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             See :mod:`matplotlib.markers` for more information about marker
             styles.
 
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters for *c*; only used
-            if *c* is an array of floats. See `~.Axes.imshow` for a detailed
-            description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4642,9 +4640,7 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
 
         Other Parameters
         ----------------
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters. See `~.Axes.imshow`
-            for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         alpha : float between 0 and 1, optional
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5276,6 +5272,7 @@ def fill_betweenx(self, y, x1, x2=0, where=None,
     # the documentation for *norm*, *vmax* and *vmin* together.
     @_api.make_keyword_only("3.5", "aspect")
     @_preprocess_data()
+    @_docstring.interpd
     def imshow(self, X, cmap=None, norm=None, aspect=None,
                interpolation=None, alpha=None,
                vmin=None, vmax=None, origin=None, extent=None, *,
@@ -5314,34 +5311,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
 
             Out-of-range RGB(A) values are clipped.
 
-        cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
-            The Colormap instance or registered colormap name used to map
-            scalar data to colors. This parameter is ignored for RGB(A) data.
-
-        norm : str or `~matplotlib.colors.Normalize`, optional
-            The normalization method used to scale scalar data to the [0, 1]
-            range before mapping to colors using *cmap*. By default, a linear
-            scaling mapping the lowest value to 0 and the highest to 1 is used.
-            This parameter is ignored for RGB(A) data.
-
-            If given, this can be one of the following:
-
-            - An instance of `.Normalize` or one of its subclasses
-              (see :doc:`/tutorials/colors/colormapnorms`).
-            - A scale name, i.e. one of "linear", "log", "symlog", "logit",
-              etc. For a full list of available scales call
-              `matplotlib.scales.get_scale_names()`.
-              In that case, a suitable `.Normalize` subclass is dynamically
-              generated and instantiated.
-
-        vmin, vmax : float, optional
-            When using scalar data and no explicit *norm*, *vmin* and *vmax*
-            define the data range that the colormap covers. By default, the
-            colormap covers the complete value range of the supplied data. It
-            is an error to use *vmin*/*vmax* when a *norm* instance is given
-            (but using a `str` *norm* name together with *vmin*/*vmax* is
-            acceptable). When using RGB(A) data, parameters *vmin*/*vmax* are
-            ignored.
+        %(cmap_norm_vmin_vmax_doc)s
 
         aspect : {'equal', 'auto'} or float, default: :rc:`image.aspect`
             The aspect ratio of the Axes.  This parameter is particularly
@@ -5664,7 +5634,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
         Parameters
         ----------
         C : 2D array-like
-            The color-mapped values.
+            The color-mapped values.  Color-mapping is controlled by *cmap*,
+            *norm*, *vmin*, and *vmax*.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5711,9 +5682,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
             See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
             for more description.
 
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters for *C*. See
-            `~.Axes.imshow` for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -5894,7 +5863,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
         Parameters
         ----------
         C : 2D array-like
-            The color-mapped values.
+            The color-mapped values.  Color-mapping is controlled by *cmap*,
+            *norm*, *vmin*, and *vmax*.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5925,9 +5895,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             expanded as needed into the appropriate 2D arrays, making a
             rectangular grid.
 
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters for *C*. See
-            `~.Axes.imshow` for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -6117,8 +6085,8 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
         C : array-like
             The image data. Supported array shapes are:
 
-            - (M, N): an image with scalar data. The data is visualized
-              using a colormap.
+            - (M, N): an image with scalar data.  Color-mapping is controlled
+              by *cmap*, *norm*, *vmin*, and *vmax*.
             - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
             - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
               i.e. including transparency.
@@ -6161,9 +6129,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
             These arguments can only be passed positionally.
 
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters for *C*. See
-            `~.Axes.imshow` for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6918,9 +6884,7 @@ def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
 
         Other Parameters
         ----------------
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters. See `~.Axes.imshow`
-            for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         alpha : ``0 <= scalar <= 1`` or ``None``, optional
             The alpha blending value.
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -633,3 +633,36 @@ def changed(self):
         """
         self.callbacks.process('changed', self)
         self.stale = True
+
+
+mpl._docstring.interpd.update(
+    # Notes: Make sure that the docstring here is generic enough to apply to
+    # all relevant plotting methods.  The description for vmin/vmax must come
+    # *last* as some methods further append information for these parameters.
+    cmap_norm_vmin_vmax_doc="""\
+cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
+    The Colormap instance or registered colormap name used to map scalar data
+    to colors. This parameter is ignored for RGB(A) data.
+
+norm : str or `~matplotlib.colors.Normalize`, optional
+    The normalization method used to scale scalar data to the [0, 1] range
+    before mapping to colors using *cmap*. By default, a linear scaling mapping
+    the lowest value to 0 and the highest to 1 is used. This parameter is
+    ignored for RGB(A) data.
+
+    If given, this can be one of the following:
+
+    - An instance of `.Normalize` or one of its subclasses
+      (see :doc:`/tutorials/colors/colormapnorms`).
+    - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc.  For a
+      list of available scales, call `matplotlib.scale.get_scale_names()`.
+      In that case, a suitable `.Normalize` subclass is dynamically generated
+      and instantiated.
+
+vmin, vmax : float, optional
+    When using scalar data and no explicit *norm*, *vmin* and *vmax* define
+    the data range that the colormap covers. By default, the colormap covers
+    the complete value range of the supplied data. It is an error to use
+    *vmin*/*vmax* when a *norm* instance is given (but using a `str` *norm*
+    name together with *vmin*/*vmax* is acceptable). When using RGB(A) data,
+    parameters *vmin*/*vmax* are ignored.""")
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -1588,7 +1588,8 @@ def _initialize_x_y(self, z):
     ``X = range(N)``, ``Y = range(M)``.
 
 Z : (M, N) array-like
-    The height values over which the contour is drawn.
+    The height values over which the contour is drawn.  Color-mapping is
+    controlled by *cmap*, *norm*, *vmin*, and *vmax*.
 
 levels : int or array-like, optional
     Determines the number and positions of the contour lines / regions.
@@ -1631,11 +1632,7 @@ def _initialize_x_y(self, z):
 alpha : float, default: 1
     The alpha blending value, between 0 (transparent) and 1 (opaque).
 
-cmap, norm, vmin, vmax
-    Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
-    for a detailed description.
-
-    *cmap* cannot be given together with *colors*.
+## cmap_norm_vmin_vmax_doc ##
 
     If *vmin* or *vmax* are not given, the default color scaling is based on
     *levels*.
@@ -1782,4 +1779,7 @@ def _initialize_x_y(self, z):
    <https://en.wikipedia.org/wiki/Marching_squares>`_ algorithm to
    compute contour locations.  More information can be found in
    `ContourPy documentation <https://contourpy.readthedocs.io>`_.
-""")
+""".replace(
+    "## cmap_norm_vmin_vmax_doc ##",
+    _docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
+)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2676,6 +2676,7 @@ def set_canvas(self, canvas):
         """
         self.canvas = canvas
 
+    @_docstring.interpd
     def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
                  vmin=None, vmax=None, origin=None, resize=False, **kwargs):
         """
@@ -2689,19 +2690,19 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
         X
             The image data. This is an array of one of the following shapes:
 
-            - MxN: luminance (grayscale) values
-            - MxNx3: RGB values
-            - MxNx4: RGBA values
+            - (M, N): an image with scalar data.  Color-mapping is controlled
+              by *cmap*, *norm*, *vmin*, and *vmax*.
+            - (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
+            - (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
+              i.e. including transparency.
 
         xo, yo : int
             The *x*/*y* image offset in pixels.
 
         alpha : None or float
             The alpha blending value.
 
-        cmap, norm, vmin, vmax
-            Data normalization and colormapping parameters for *X*. See
-            `~.Axes.imshow` for a detailed description.
+        %(cmap_norm_vmin_vmax_doc)s
 
         origin : {'upper', 'lower'}, default: :rc:`image.origin`
             Indicates where the [0, 0] index of the array is in the upper left
diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -109,7 +109,8 @@ def _contour_args(self, args, kwargs):
     This is mutually exclusive with specifying *triangulation*.
 
 Z : array-like
-    The height values over which the contour is drawn.
+    The height values over which the contour is drawn.  Color-mapping is
+    controlled by *cmap*, *norm*, *vmin*, and *vmax*.
 
 levels : int or array-like, optional
     Determines the number and positions of the contour lines / regions.
@@ -143,11 +144,7 @@ def _contour_args(self, args, kwargs):
 alpha : float, default: 1
     The alpha blending value, between 0 (transparent) and 1 (opaque).
 
-cmap, norm, vmin, vmax
-    Data normalization and colormapping parameters for *Z*. See `~.Axes.imshow`
-    for a detailed description.
-
-    *cmap* cannot be given together with *colors*.
+## cmap_norm_vmin_vmax_doc ##
 
     If *vmin* or *vmax* are not given, the default color scaling is based on
     *levels*.
@@ -205,7 +202,10 @@ def _contour_args(self, args, kwargs):
 antialiased : bool, optional
     Enable antialiasing, overriding the defaults.  For
     filled contours, the default is *True*.  For line contours,
-    it is taken from :rc:`lines.antialiased`.""")
+    it is taken from :rc:`lines.antialiased`.""".replace(
+    "## cmap_norm_vmin_vmax_doc ##",
+    _docstring.interpd.params["cmap_norm_vmin_vmax_doc"])
+)
 
 
 @_docstring.Substitution(func='tricontour', type='lines')
