Use docstring interpolation instead.

anntzer · anntzer · commit 649eb06efc52 · 2022-06-23T23:41:34.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,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(vmin_vmax_doc)s
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -4642,9 +4644,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(vmin_vmax_doc)s
 
         alpha : float between 0 and 1, optional
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -5276,6 +5280,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 +5319,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(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 +5646,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 +5694,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(vmin_vmax_doc)s
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -5894,7 +5879,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 +5911,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(vmin_vmax_doc)s
 
         edgecolors : {'none', None, 'face', color, color sequence}, optional
             The color of the edges. Defaults to 'none'. Possible values:
@@ -6117,8 +6105,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 +6149,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(vmin_vmax_doc)s
 
         alpha : float, default: None
             The alpha blending value, between 0 (transparent) and 1 (opaque).
@@ -6918,9 +6908,11 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(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,35 @@ def changed(self):
         """
         self.callbacks.process('changed', self)
         self.stale = True
+
+
+# The docstrings here must be generic enough to apply to all relevant methods.
+mpl._docstring.interpd.update(
+    cmap_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_doc="""\
+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_doc="""\
+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,11 @@ 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_doc)s
 
-    *cmap* cannot be given together with *colors*.
+%(norm_doc)s
+
+%(vmin_vmax_doc)s
 
     If *vmin* or *vmax* are not given, the default color scaling is based on
     *levels*.
@@ -1782,4 +1783,5 @@ 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>`_.
-""")
+""" % _docstring.interpd.params,
+)
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,23 @@ 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_doc)s
+
+        %(norm_doc)s
+
+        %(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
@@ -82,12 +82,12 @@ def _contour_args(self, args, kwargs):
 
 
 _docstring.interpd.update(_tricontour_doc="""
-Draw contour %(type)s on an unstructured triangular grid.
+Draw contour %%(type)s on an unstructured triangular grid.
 
 Call signatures::
 
-    %(func)s(triangulation, Z, [levels], ...)
-    %(func)s(x, y, Z, [levels], *, [triangles=triangles], [mask=mask], ...)
+    %%(func)s(triangulation, Z, [levels], ...)
+    %%(func)s(x, y, Z, [levels], *, [triangles=triangles], [mask=mask], ...)
 
 The triangular grid can be specified either by passing a `.Triangulation`
 object as the first parameter, or by passing the points *x*, *y* and
@@ -96,7 +96,7 @@ def _contour_args(self, args, kwargs):
 *triangles* are given, the triangulation is calculated on the fly.
 
 It is possible to pass *triangles* positionally, i.e.
-``%(func)s(x, y, triangles, Z, ...)``. However, this is discouraged. For more
+``%%(func)s(x, y, triangles, Z, ...)``. However, this is discouraged. For more
 clarity, pass *triangles* via keyword argument.
 
 Parameters
@@ -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.
@@ -128,7 +129,7 @@ def _contour_args(self, args, kwargs):
 Other Parameters
 ----------------
 colors : color string or sequence of colors, optional
-    The colors of the levels, i.e., the contour %(type)s.
+    The colors of the levels, i.e., the contour %%(type)s.
 
     The sequence is cycled for the levels in ascending order. If the sequence
     is shorter than the number of levels, it's repeated.
@@ -143,11 +144,11 @@ 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_doc)s
 
-    *cmap* cannot be given together with *colors*.
+%(norm_doc)s
+
+%(vmin_vmax_doc)s
 
     If *vmin* or *vmax* are not given, the default color scaling is based on
     *levels*.
@@ -177,7 +178,7 @@ def _contour_args(self, args, kwargs):
     Defaults to `~.ticker.MaxNLocator`.
 
 extend : {'neither', 'both', 'min', 'max'}, default: 'neither'
-    Determines the ``%(func)s``-coloring of values that are outside the
+    Determines the ``%%(func)s``-coloring of values that are outside the
     *levels* range.
 
     If 'neither', values outside the *levels* range are not colored.  If 'min',
@@ -205,7 +206,8 @@ 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`.""" % _docstring.interpd.params,
+)
 
 
 @_docstring.Substitution(func='tricontour', type='lines')
