Move colorbar() doc to method itself.

anntzer · anntzer · commit 00156878ab2b · 2022-08-07T11:17:42.000+02:00
It seems clearer to just put in the docstring "as is" at the (only)
expected place rather than define it in another module and move it
around.

Also group all "other parameters" together into a standard numpydoc
section, which avoids having to fiddle with indents.
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -12,7 +12,6 @@
 """
 
 import logging
-import textwrap
 
 import numpy as np
 
@@ -28,7 +27,8 @@
 
 _log = logging.getLogger(__name__)
 
-_make_axes_kw_doc = """
+_docstring.interpd.update(
+    _make_axes_kw_doc="""
 location : None or {'left', 'right', 'top', 'bottom'}
     The location, relative to the parent axes, where the colorbar axes
     is created.  It also determines the *orientation* of the colorbar
@@ -61,10 +61,8 @@
 panchor : (float, float), or *False*, optional
     The anchor point of the colorbar parent axes. If *False*, the parent
     axes' anchor will be unchanged.
-    Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
-"""
-
-_colormap_kw_doc = """
+    Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.""",
+    _colormap_kw_doc="""
 extend : {'neither', 'both', 'min', 'max'}
     Make pointed end(s) for out-of-range values (unless 'neither').  These are
     set for a given colormap using the colormap set_under and set_over methods.
@@ -114,76 +112,7 @@
     each region delimited by adjacent entries in *boundaries*, the color mapped
     to the corresponding value in values will be used.
     Normally only useful for indexed colors (i.e. ``norm=NoNorm()``) or other
-    unusual circumstances.
-"""
-
-_docstring.interpd.update(colorbar_doc="""
-Add a colorbar to a plot.
-
-Parameters
-----------
-mappable
-    The `matplotlib.cm.ScalarMappable` (i.e., `~matplotlib.image.AxesImage`,
-    `~matplotlib.contour.ContourSet`, etc.) described by this colorbar.
-    This argument is mandatory for the `.Figure.colorbar` method but optional
-    for the `.pyplot.colorbar` function, which sets the default to the current
-    image.
-
-    Note that one can create a `.ScalarMappable` "on-the-fly" to generate
-    colorbars not attached to a previously drawn artist, e.g. ::
-
-        fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)
-
-cax : `~matplotlib.axes.Axes`, optional
-    Axes into which the colorbar will be drawn.
-
-ax : `~matplotlib.axes.Axes`, list of Axes, optional
-    One or more parent axes from which space for a new colorbar axes will be
-    stolen, if *cax* is None.  This has no effect if *cax* is set.
-
-use_gridspec : bool, optional
-    If *cax* is ``None``, a new *cax* is created as an instance of Axes.  If
-    *ax* is an instance of Subplot and *use_gridspec* is ``True``, *cax* is
-    created as an instance of Subplot using the :mod:`.gridspec` module.
-
-Returns
--------
-colorbar : `~matplotlib.colorbar.Colorbar`
-
-Notes
------
-Additional keyword arguments are of two kinds:
-
-  axes properties:
-%s
-  colorbar properties:
-%s
-
-If *mappable* is a `~.contour.ContourSet`, its *extend* kwarg is included
-automatically.
-
-The *shrink* kwarg provides a simple way to scale the colorbar with respect
-to the axes. Note that if *cax* is specified, it determines the size of the
-colorbar and *shrink* and *aspect* kwargs are ignored.
-
-For more precise control, you can manually specify the positions of
-the axes objects in which the mappable and the colorbar are drawn.  In
-this case, do not use any of the axes properties kwargs.
-
-It is known that some vector graphics viewers (svg and pdf) renders white gaps
-between segments of the colorbar.  This is due to bugs in the viewers, not
-Matplotlib.  As a workaround, the colorbar can be rendered with overlapping
-segments::
-
-    cbar = colorbar()
-    cbar.solids.set_edgecolor("face")
-    draw()
-
-However this has negative consequences in other circumstances, e.g. with
-semi-transparent images (alpha < 1) and colorbar extensions; therefore, this
-workaround is not used by default (see issue #1188).
-""" % (textwrap.indent(_make_axes_kw_doc, "    "),
-       textwrap.indent(_colormap_kw_doc, "    ")))
+    unusual circumstances.""")
 
 
 def _set_ticks_on_axis_warn(*args, **kwargs):
@@ -267,7 +196,7 @@ def get_subplotspec(self):
         return ss()
 
 
-@_docstring.Substitution(_colormap_kw_doc)
+@_docstring.interpd
 class Colorbar:
     r"""
     Draw a colorbar in an existing axes.
@@ -327,7 +256,7 @@ class Colorbar:
     drawedges : bool
 
     filled : bool
-    %s
+    %(_colormap_kw_doc)s
     """
 
     n_rasterize = 50  # rasterize solids if number of colors >= n_rasterize
@@ -1404,7 +1333,7 @@ def _normalize_location_orientation(location, orientation):
     return loc_settings
 
 
-@_docstring.Substitution(_make_axes_kw_doc)
+@_docstring.interpd
 def make_axes(parents, location=None, orientation=None, fraction=0.15,
               shrink=1.0, aspect=20, **kwargs):
     """
@@ -1417,7 +1346,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
     ----------
     parents : `~.axes.Axes` or list of `~.axes.Axes`
         The Axes to use as parents for placing the colorbar.
-    %s
+    %(_make_axes_kw_doc)s
 
     Returns
     -------
@@ -1506,7 +1435,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15,
     return cax, kwargs
 
 
-@_docstring.Substitution(_make_axes_kw_doc)
+@_docstring.interpd
 def make_axes_gridspec(parent, *, location=None, orientation=None,
                        fraction=0.15, shrink=1.0, aspect=20, **kwargs):
     """
@@ -1532,7 +1461,7 @@ def make_axes_gridspec(parent, *, location=None, orientation=None,
     ----------
     parent : `~.axes.Axes`
         The Axes to use as parent for placing the colorbar.
-    %s
+    %(_make_axes_kw_doc)s
 
     Returns
     -------
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1183,7 +1183,74 @@ def text(self, x, y, s, fontdict=None, **kwargs):
     @_docstring.dedent_interpd
     def colorbar(
             self, mappable, cax=None, ax=None, use_gridspec=True, **kwargs):
-        """%(colorbar_doc)s"""
+        """
+        Add a colorbar to a plot.
+
+        Parameters
+        ----------
+        mappable
+            The `matplotlib.cm.ScalarMappable` (i.e., `.AxesImage`,
+            `.ContourSet`, etc.) described by this colorbar.  This argument is
+            mandatory for the `.Figure.colorbar` method but optional for the
+            `.pyplot.colorbar` function, which sets the default to the current
+            image.
+
+            Note that one can create a `.ScalarMappable` "on-the-fly" to
+            generate colorbars not attached to a previously drawn artist, e.g.
+            ::
+
+                fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)
+
+        cax : `~matplotlib.axes.Axes`, optional
+            Axes into which the colorbar will be drawn.
+
+        ax : `~matplotlib.axes.Axes`, list of Axes, optional
+            One or more parent axes from which space for a new colorbar axes
+            will be stolen, if *cax* is None.  This has no effect if *cax* is
+            set.
+
+        use_gridspec : bool, optional
+            If *cax* is ``None``, a new *cax* is created as an instance of
+            Axes.  If *ax* is an instance of Subplot and *use_gridspec* is
+            ``True``, *cax* is created as an instance of Subplot using the
+            :mod:`.gridspec` module.
+
+        Returns
+        -------
+        colorbar : `~matplotlib.colorbar.Colorbar`
+
+        Other Parameters
+        ----------------
+        %(_make_axes_kw_doc)s
+        %(_colormap_kw_doc)s
+
+        Notes
+        -----
+        If *mappable* is a `~.contour.ContourSet`, its *extend* kwarg is
+        included automatically.
+
+        The *shrink* kwarg provides a simple way to scale the colorbar with
+        respect to the axes. Note that if *cax* is specified, it determines the
+        size of the colorbar and *shrink* and *aspect* kwargs are ignored.
+
+        For more precise control, you can manually specify the positions of the
+        axes objects in which the mappable and the colorbar are drawn.  In this
+        case, do not use any of the axes properties kwargs.
+
+        It is known that some vector graphics viewers (svg and pdf) renders
+        white gaps between segments of the colorbar.  This is due to bugs in
+        the viewers, not Matplotlib.  As a workaround, the colorbar can be
+        rendered with overlapping segments::
+
+            cbar = colorbar()
+            cbar.solids.set_edgecolor("face")
+            draw()
+
+        However this has negative consequences in other circumstances, e.g.
+        with semi-transparent images (alpha < 1) and colorbar extensions;
+        therefore, this workaround is not used by default (see issue #1188).
+        """
+
         if ax is None:
             ax = getattr(mappable, "axes", self.gca())
 
