Reorganize colorbar docstrings.

anntzer · anntzer · commit 899af8e55a93 · 2020-06-27T12:33:18.000+02:00
- Figure.colorbar and pyplot.colorbar can use the docstring (no need to
  restate the signatures, IPython/pydoc/sphinx does that for you).
- Deprecate some docstrings that exist as globals at the module level.
- Clarify what happens when `cax` and `ax` are both given (we can always
  emit a warning and deprecate that behavior later).
diff --git a/doc/api/api_changes_3.4/deprecations.rst b/doc/api/api_changes_3.4/deprecations.rst
@@ -4,3 +4,8 @@ Deprecations
 ``dpi_cor`` property of `.FancyArrowPatch`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This parameter is considered internal and deprecated.
+
+Colorbar docstrings
+~~~~~~~~~~~~~~~~~~~
+The following globals in :mod:`matplotlib.colorbar` are deprecated:
+``colorbar_doc``, ``colormap_kw_doc``, ``make_axes_kw_doc``.
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -84,9 +84,8 @@
         axes' anchor will be unchanged.
         Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal.
 """
-make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc
 
-colormap_kw_doc = """
+_colormap_kw_doc = """
 
     ============  ====================================================
     Property      Description
@@ -149,18 +148,9 @@
 
 """
 
-colorbar_doc = """
-
+docstring.interpd.update(colorbar_doc="""
 Add a colorbar to a plot.
 
-Function signatures for the :mod:`~matplotlib.pyplot` interface; all
-but the first are also method signatures for the `~.Figure.colorbar` method::
-
-  colorbar(**kwargs)
-  colorbar(mappable, **kwargs)
-  colorbar(mappable, cax=cax, **kwargs)
-  colorbar(mappable, ax=ax, **kwargs)
-
 Parameters
 ----------
 mappable
@@ -179,9 +169,8 @@
     Axes into which the colorbar will be drawn.
 
 ax : `~matplotlib.axes.Axes`, list of Axes, optional
-    Parent axes from which space for a new colorbar axes will be stolen.
-    If a list of axes is given they will all be resized to make room for the
-    colorbar axes.
+    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
@@ -198,6 +187,7 @@
 Additional keyword arguments are of two kinds:
 
   axes properties:
+%s
 %s
   colorbar properties:
 %s
@@ -225,10 +215,12 @@
 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).
+""" % (_make_axes_param_doc, _make_axes_other_param_doc, _colormap_kw_doc))
 
-""" % (make_axes_kw_doc, colormap_kw_doc)
-
-docstring.interpd.update(colorbar_doc=colorbar_doc)
+# Deprecated since 3.4.
+colorbar_doc = docstring.interpd.params["colorbar_doc"]
+colormap_kw_doc = _colormap_kw_doc
+make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc
 
 
 def _set_ticks_on_axis_warn(*args, **kw):
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2315,12 +2315,7 @@ def savefig(self, fname, *, transparent=None, **kwargs):
 
     @docstring.dedent_interpd
     def colorbar(self, mappable, cax=None, ax=None, use_gridspec=True, **kw):
-        """
-        Create a colorbar for a ScalarMappable instance, *mappable*.
-
-        Documentation for the pyplot thin wrapper:
-        %(colorbar_doc)s
-        """
+        """%(colorbar_doc)s"""
         if ax is None:
             ax = self.gca()
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2172,6 +2172,7 @@ def _setup_pyplot_info_docstrings():
 ## Plotting part 1: manually generated functions and wrappers ##
 
 
+@_copy_docstring_and_deprecators(Figure.colorbar)
 def colorbar(mappable=None, cax=None, ax=None, **kw):
     if mappable is None:
         mappable = gci()
@@ -2184,7 +2185,6 @@ def colorbar(mappable=None, cax=None, ax=None, **kw):
         ax = gca()
     ret = gcf().colorbar(mappable, cax=cax, ax=ax, **kw)
     return ret
-colorbar.__doc__ = matplotlib.colorbar.colorbar_doc
 
 
 def clim(vmin=None, vmax=None):
