List existing rcParams in rcParams docstring.

anntzer · anntzer · commit 916f4ff7e9f4 · 2020-09-09T17:38:43.000+02:00
This is useful for those who mostly live at the command line, letting
one see the list of rcParams with `pydoc matplotlib.rcParams` (for
example).

Making `Substitution` always perform docstring dedenting simplifies the
implementation here; I'm not sure you'd ever\* want to do an un-dedented
interpolation anyways... (\*for certain values of "ever")  Fix colorbar
docstrings indentation accordingly.
diff --git a/doc/api/next_api_changes/behavior/18440-AL.rst b/doc/api/next_api_changes/behavior/18440-AL.rst
@@ -0,0 +1,2 @@
+docstring.Substitution now always dedents docstrings before string interpolation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -104,7 +104,7 @@
 
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
-from . import cbook, rcsetup
+from . import cbook, docstring, rcsetup
 from matplotlib.cbook import MatplotlibDeprecationWarning, sanitize_sequence
 from matplotlib.cbook import mplDeprecation  # deprecated
 from matplotlib.rcsetup import validate_backend, cycler
@@ -635,13 +635,18 @@ def gen_candidates():
 _all_deprecated = {*_deprecated_map, *_deprecated_ignore_map}
 
 
+@docstring.Substitution("\n".join(map("- {}".format, rcsetup._validators)))
 class RcParams(MutableMapping, dict):
     """
     A dictionary object including validation.
 
     Validating functions are defined and associated with rc parameters in
     :mod:`matplotlib.rcsetup`.
 
+    The list of rcParams is:
+
+    %s
+
     See Also
     --------
     :ref:`customizing-with-matplotlibrc-files`
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -33,6 +33,7 @@
 
 import copy
 import logging
+import textwrap
 
 import numpy as np
 
@@ -53,35 +54,34 @@
 _log = logging.getLogger(__name__)
 
 _make_axes_param_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
-        (colorbars on the left and right are vertical, colorbars at the top
-        and bottom are horizontal).  If None, the location will come from the
-        *orientation* if it is set (vertical colorbars on the right, horizontal
-        ones at the bottom), or default to 'right' if *orientation* is unset.
-    orientation : None or {'vertical', 'horizontal'}
-        The orientation of the colorbar.  It is preferrable to set the
-        *location* of the colorbar, as that also determines the *orientation*;
-        passing incompatible values for *location* and *orientation* raises an
-        exception.
-    fraction : float, default: 0.15
-        Fraction of original axes to use for colorbar.
-    shrink : float, default: 1.0
-        Fraction by which to multiply the size of the colorbar.
-    aspect : float, default: 20
-        Ratio of long to short dimensions.
+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
+    (colorbars on the left and right are vertical, colorbars at the top
+    and bottom are horizontal).  If None, the location will come from the
+    *orientation* if it is set (vertical colorbars on the right, horizontal
+    ones at the bottom), or default to 'right' if *orientation* is unset.
+orientation : None or {'vertical', 'horizontal'}
+    The orientation of the colorbar.  It is preferrable to set the *location*
+    of the colorbar, as that also determines the *orientation*; passing
+    incompatible values for *location* and *orientation* raises an exception.
+fraction : float, default: 0.15
+    Fraction of original axes to use for colorbar.
+shrink : float, default: 1.0
+    Fraction by which to multiply the size of the colorbar.
+aspect : float, default: 20
+    Ratio of long to short dimensions.
 """
 _make_axes_other_param_doc = """
-    pad : float, default: 0.05 if vertical, 0.15 if horizontal
-        Fraction of original axes between colorbar and new image axes.
-    anchor : (float, float), optional
-        The anchor point of the colorbar axes.
-        Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
-    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.
+pad : float, default: 0.05 if vertical, 0.15 if horizontal
+    Fraction of original axes between colorbar and new image axes.
+anchor : (float, float), optional
+    The anchor point of the colorbar axes.
+    Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal.
+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 = """
@@ -214,7 +214,9 @@
 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))
+""" % (textwrap.indent(_make_axes_param_doc, "    "),
+       textwrap.indent(_make_axes_other_param_doc, "    "),
+       _colormap_kw_doc))
 
 # Deprecated since 3.4.
 colorbar_doc = docstring.interpd.params["colorbar_doc"]
diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py
@@ -37,7 +37,7 @@ def __init__(self, *args, **kwargs):
 
     def __call__(self, func):
         if func.__doc__:
-            func.__doc__ %= self.params
+            func.__doc__ = inspect.cleandoc(func.__doc__) % self.params
         return func
 
     def update(self, *args, **kwargs):
@@ -72,9 +72,4 @@ def do_copy(target):
 # Create a decorator that will house the various docstring snippets reused
 # throughout Matplotlib.
 interpd = Substitution()
-
-
-def dedent_interpd(func):
-    """Dedent *func*'s docstring, then interpolate it with ``interpd``."""
-    func.__doc__ = inspect.getdoc(func)
-    return interpd(func)
+dedent_interpd = interpd
