diff --git a/doc/api/next_api_changes/2018-01-08-AL.rst b/doc/api/next_api_changes/2018-01-08-AL.rst
new file mode 100644
index 000000000000..f4cf24b8fa85
--- /dev/null
+++ b/doc/api/next_api_changes/2018-01-08-AL.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+``cbook.dedent``, ``docstring.Appender``, ``docstring.dedent``, and
+``docstring.copy_dedent`` are deprecated (use the standard library's docstring
+manipulation tools, such as `inspect.cleandoc` and `inspect.getdoc` instead).
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
index 923bc41170dd..1d2dd4892724 100644
--- a/lib/matplotlib/__init__.py
+++ b/lib/matplotlib/__init__.py
@@ -1441,7 +1441,7 @@ def _add_data_doc(docstring, replace_names):
     -------
         The augmented docstring.
     """
-    docstring = dedent(docstring) if docstring is not None else ""
+    docstring = inspect.cleandoc(docstring) if docstring is not None else ""
     repl = ("* All positional and all keyword arguments."
             if replace_names is None else
             ""
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
index 775ad6d53e39..7c0416d2180f 100644
--- a/lib/matplotlib/cbook/__init__.py
+++ b/lib/matplotlib/cbook/__init__.py
@@ -559,6 +559,7 @@ def get_realpath_and_stat(path):
 _dedent_regex = {}
 
 
+@deprecated("3.1", alternative="inspect.cleandoc")
 def dedent(s):
     """
     Remove excess indentation from docstring *s*.
diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py
index a97d10391eb2..79ea63a964c2 100644
--- a/lib/matplotlib/docstring.py
+++ b/lib/matplotlib/docstring.py
@@ -1,45 +1,49 @@
+import inspect
+
 from matplotlib import cbook
 
 
 class Substitution(object):
     """
-    A decorator to take a function's docstring and perform string
-    substitution on it.
+    A decorator that performs %-substitution on an object's docstring.
 
-    This decorator should be robust even if func.__doc__ is None
-    (for example, if -OO was passed to the interpreter)
+    This decorator should be robust even if ``obj.__doc__`` is None (for
+    example, if -OO was passed to the interpreter).
 
-    Usage: construct a docstring.Substitution with a sequence or
-    dictionary suitable for performing substitution; then
-    decorate a suitable function with the constructed object. e.g.
+    Usage: construct a docstring.Substitution with a sequence or dictionary
+    suitable for performing substitution; then decorate a suitable function
+    with the constructed object, e.g.::
 
-    sub_author_name = Substitution(author='Jason')
+        sub_author_name = Substitution(author='Jason')
 
-    @sub_author_name
-    def some_function(x):
-        "%(author)s wrote this function"
+        @sub_author_name
+        def some_function(x):
+            "%(author)s wrote this function"
 
-    # note that some_function.__doc__ is now "Jason wrote this function"
+        # note that some_function.__doc__ is now "Jason wrote this function"
 
-    One can also use positional arguments.
+    One can also use positional arguments::
 
-    sub_first_last_names = Substitution('Edgar Allen', 'Poe')
+        sub_first_last_names = Substitution('Edgar Allen', 'Poe')
 
-    @sub_first_last_names
-    def some_function(x):
-        "%s %s wrote the Raven"
+        @sub_first_last_names
+        def some_function(x):
+            "%s %s wrote the Raven"
     """
     def __init__(self, *args, **kwargs):
-        assert not (len(args) and len(kwargs)), \
-                "Only positional or keyword args are allowed"
+        if args and kwargs:
+            raise TypeError("Only positional or keyword args are allowed")
         self.params = args or kwargs
 
     def __call__(self, func):
-        func.__doc__ = func.__doc__ and func.__doc__ % self.params
+        if func.__doc__:
+            func.__doc__ %= self.params
         return func
 
     def update(self, *args, **kwargs):
-        "Assume self.params is a dict and update it with supplied args"
+        """
+        Update ``self.params`` (which must be a dict) with the supplied args.
+        """
         self.params.update(*args, **kwargs)
 
     @classmethod
@@ -55,6 +59,7 @@ def from_params(cls, params):
         return result
 
 
+@cbook.deprecated("3.1")
 class Appender(object):
     """
     A function decorator that will append an addendum to the docstring
@@ -84,6 +89,7 @@ def __call__(self, func):
         return func
 
 
+@cbook.deprecated("3.1", alternative="inspect.getdoc()")
 def dedent(func):
     "Dedent a docstring (if present)"
     func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__)
@@ -98,17 +104,19 @@ def do_copy(target):
         return target
     return do_copy
 
-# create a decorator that will house the various documentation that
-#  is reused throughout matplotlib
+
+# Create a decorator that will house the various docstring snippets reused
+# throughout Matplotlib.
 interpd = Substitution()
 
 
 def dedent_interpd(func):
-    """A special case of the interpd that first performs a dedent on
-    the incoming docstring"""
-    return interpd(dedent(func))
+    """Dedent *func*'s docstring, then interpolate it with ``interpd``."""
+    func.__doc__ = inspect.getdoc(func.__doc__)
+    return interpd(func)
 
 
+@cbook.deprecated("3.1", alternative="docstring.copy() and cbook.dedent()")
 def copy_dedent(source):
     """A decorator that will copy the docstring from the source and
     then dedent it"""
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
index e2a9173cfa9b..072cd8ce0d2e 100644
--- a/lib/matplotlib/mlab.py
+++ b/lib/matplotlib/mlab.py
@@ -54,6 +54,7 @@
 """
 
 import csv
+import inspect
 
 import numpy as np
 
@@ -618,7 +619,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 
 
 # Split out these keyword docs so that they can be used elsewhere
-docstring.interpd.update(Spectral=cbook.dedent("""
+docstring.interpd.update(Spectral=inspect.cleandoc("""
     Fs : scalar
         The sampling frequency (samples per time unit).  It is used
         to calculate the Fourier frequencies, freqs, in cycles per time
@@ -640,7 +641,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 """))
 
 
-docstring.interpd.update(Single_Spectrum=cbook.dedent("""
+docstring.interpd.update(Single_Spectrum=inspect.cleandoc("""
     pad_to : int
         The number of points to which the data segment is padded when
         performing the FFT.  While not increasing the actual resolution of
@@ -652,7 +653,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
 """))
 
 
-docstring.interpd.update(PSD=cbook.dedent("""
+docstring.interpd.update(PSD=inspect.cleandoc("""
     pad_to : int
         The number of points to which the data segment is padded when
         performing the FFT.  This can be different from *NFFT*, which
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
index 0a025ed2f96a..565e7baae2c6 100644
--- a/lib/matplotlib/patches.py
+++ b/lib/matplotlib/patches.py
@@ -1,5 +1,6 @@
 import contextlib
 import functools
+import inspect
 import math
 from numbers import Number
 import textwrap
@@ -2435,8 +2436,8 @@ def transmute(self, x0, y0, width, height, mutation_size):
             return Path(saw_vertices, codes)
 
     if __doc__:  # __doc__ could be None if -OO optimization is enabled
-        __doc__ = cbook.dedent(__doc__) % \
-               {"AvailableBoxstyles": _pprint_styles(_style_list)}
+        __doc__ = inspect.cleandoc(__doc__) % {
+            "AvailableBoxstyles": _pprint_styles(_style_list)}
 
 docstring.interpd.update(
     AvailableBoxstyles=_pprint_styles(BoxStyle._style_list),
@@ -3104,8 +3105,8 @@ def connect(self, posA, posB):
             return Path(vertices, codes)
 
     if __doc__:
-        __doc__ = cbook.dedent(__doc__) % \
-               {"AvailableConnectorstyles": _pprint_styles(_style_list)}
+        __doc__ = inspect.cleandoc(__doc__) % {
+            "AvailableConnectorstyles": _pprint_styles(_style_list)}
 
 
 def _point_along_a_line(x0, y0, x1, y1, d):
@@ -3895,8 +3896,8 @@ def transmute(self, path, mutation_size, linewidth):
             return path, True
 
     if __doc__:
-        __doc__ = cbook.dedent(__doc__) % \
-               {"AvailableArrowstyles": _pprint_styles(_style_list)}
+        __doc__ = inspect.cleandoc(__doc__) % {
+            "AvailableArrowstyles": _pprint_styles(_style_list)}
 
 
 docstring.interpd.update(
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index c61cf1f3e775..62500aedba86 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -167,7 +167,7 @@ def uninstall_repl_displayhook():
 draw_all = _pylab_helpers.Gcf.draw_all
 
 
-@docstring.copy_dedent(Artist.findobj)
+@docstring.copy(Artist.findobj)
 def findobj(o=None, match=None, include_self=True):
     if o is None:
         o = gcf()
@@ -300,17 +300,17 @@ def pause(interval):
         time.sleep(interval)
 
 
-@docstring.copy_dedent(matplotlib.rc)
+@docstring.copy(matplotlib.rc)
 def rc(group, **kwargs):
     matplotlib.rc(group, **kwargs)
 
 
-@docstring.copy_dedent(matplotlib.rc_context)
+@docstring.copy(matplotlib.rc_context)
 def rc_context(rc=None, fname=None):
     return matplotlib.rc_context(rc, fname)
 
 
-@docstring.copy_dedent(matplotlib.rcdefaults)
+@docstring.copy(matplotlib.rcdefaults)
 def rcdefaults():
     matplotlib.rcdefaults()
     if matplotlib.is_interactive():
@@ -612,12 +612,12 @@ def get_current_fig_manager():
     return figManager
 
 
-@docstring.copy_dedent(FigureCanvasBase.mpl_connect)
+@docstring.copy(FigureCanvasBase.mpl_connect)
 def connect(s, func):
     return get_current_fig_manager().canvas.mpl_connect(s, func)
 
 
-@docstring.copy_dedent(FigureCanvasBase.mpl_disconnect)
+@docstring.copy(FigureCanvasBase.mpl_disconnect)
 def disconnect(cid):
     return get_current_fig_manager().canvas.mpl_disconnect(cid)
 
@@ -687,7 +687,7 @@ def draw():
     get_current_fig_manager().canvas.draw_idle()
 
 
-@docstring.copy_dedent(Figure.savefig)
+@docstring.copy(Figure.savefig)
 def savefig(*args, **kwargs):
     fig = gcf()
     res = fig.savefig(*args, **kwargs)
@@ -695,7 +695,7 @@ def savefig(*args, **kwargs):
     return res
 
 
-@docstring.copy_dedent(Figure.ginput)
+@docstring.copy(Figure.ginput)
 def ginput(*args, **kwargs):
     """
     Blocking call to interact with the figure.
@@ -708,7 +708,7 @@ def ginput(*args, **kwargs):
     return gcf().ginput(*args, **kwargs)
 
 
-@docstring.copy_dedent(Figure.waitforbuttonpress)
+@docstring.copy(Figure.waitforbuttonpress)
 def waitforbuttonpress(*args, **kwargs):
     """
     Blocking call to interact with the figure.
@@ -725,17 +725,17 @@ def waitforbuttonpress(*args, **kwargs):
 ## Putting things in figures ##
 
 
-@docstring.copy_dedent(Figure.text)
+@docstring.copy(Figure.text)
 def figtext(x, y, s, *args, **kwargs):
     return gcf().text(x, y, s, *args, **kwargs)
 
 
-@docstring.copy_dedent(Figure.suptitle)
+@docstring.copy(Figure.suptitle)
 def suptitle(t, **kwargs):
     return gcf().suptitle(t, **kwargs)
 
 
-@docstring.copy_dedent(Figure.figimage)
+@docstring.copy(Figure.figimage)
 def figimage(*args, **kwargs):
     return gcf().figimage(*args, **kwargs)
 
@@ -2104,12 +2104,12 @@ def set_cmap(cmap):
         im.set_cmap(cmap)
 
 
-@docstring.copy_dedent(matplotlib.image.imread)
+@docstring.copy(matplotlib.image.imread)
 def imread(fname, format=None):
     return matplotlib.image.imread(fname, format)
 
 
-@docstring.copy_dedent(matplotlib.image.imsave)
+@docstring.copy(matplotlib.image.imsave)
 def imsave(fname, arr, **kwargs):
     return matplotlib.image.imsave(fname, arr, **kwargs)
 
@@ -2320,14 +2320,6 @@ def getname_val(identifier):
         fig.autofmt_xdate()
 
 
-def _autogen_docstring(base):
-    """Autogenerated wrappers will get their docstring from a base function
-    with an addendum."""
-    msg = ''
-    addendum = docstring.Appender(msg, '\n\n')
-    return lambda func: addendum(docstring.copy_dedent(base)(func))
-
-
 # If rcParams['backend_fallback'] is true, and an interactive backend is
 # requested, ignore rcParams['backend'] and force selection of a backend that
 # is compatible with the current running interactive framework.
@@ -2350,14 +2342,14 @@ def _autogen_docstring(base):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.acorr)
+@docstring.copy(Axes.acorr)
 def acorr(x, *, data=None, **kwargs):
     return gca().acorr(
         x, **({"data": data} if data is not None else {}), **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.angle_spectrum)
+@docstring.copy(Axes.angle_spectrum)
 def angle_spectrum(
         x, Fs=None, Fc=None, window=None, pad_to=None, sides=None, *,
         data=None, **kwargs):
@@ -2367,55 +2359,55 @@ def angle_spectrum(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.annotate)
+@docstring.copy(Axes.annotate)
 def annotate(s, xy, *args, **kwargs):
     return gca().annotate(s, xy, *args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.arrow)
+@docstring.copy(Axes.arrow)
 def arrow(x, y, dx, dy, **kwargs):
     return gca().arrow(x, y, dx, dy, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.autoscale)
+@docstring.copy(Axes.autoscale)
 def autoscale(enable=True, axis='both', tight=None):
     return gca().autoscale(enable=enable, axis=axis, tight=tight)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.axhline)
+@docstring.copy(Axes.axhline)
 def axhline(y=0, xmin=0, xmax=1, **kwargs):
     return gca().axhline(y=y, xmin=xmin, xmax=xmax, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.axhspan)
+@docstring.copy(Axes.axhspan)
 def axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs):
     return gca().axhspan(ymin, ymax, xmin=xmin, xmax=xmax, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.axis)
+@docstring.copy(Axes.axis)
 def axis(*v, **kwargs):
     return gca().axis(*v, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.axvline)
+@docstring.copy(Axes.axvline)
 def axvline(x=0, ymin=0, ymax=1, **kwargs):
     return gca().axvline(x=x, ymin=ymin, ymax=ymax, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.axvspan)
+@docstring.copy(Axes.axvspan)
 def axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs):
     return gca().axvspan(xmin, xmax, ymin=ymin, ymax=ymax, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.bar)
+@docstring.copy(Axes.bar)
 def bar(
         x, height, width=0.8, bottom=None, *, align='center',
         data=None, **kwargs):
@@ -2425,21 +2417,21 @@ def bar(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.barbs)
+@docstring.copy(Axes.barbs)
 def barbs(*args, data=None, **kw):
     return gca().barbs(
         *args, **({"data": data} if data is not None else {}), **kw)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.barh)
+@docstring.copy(Axes.barh)
 def barh(y, width, height=0.8, left=None, *, align='center', **kwargs):
     return gca().barh(
         y, width, height=height, left=left, align=align, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.boxplot)
+@docstring.copy(Axes.boxplot)
 def boxplot(
         x, notch=None, sym=None, vert=None, whis=None,
         positions=None, widths=None, patch_artist=None,
@@ -2464,7 +2456,7 @@ def boxplot(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.broken_barh)
+@docstring.copy(Axes.broken_barh)
 def broken_barh(xranges, yrange, *, data=None, **kwargs):
     return gca().broken_barh(
         xranges, yrange, **({"data": data} if data is not None else
@@ -2472,19 +2464,19 @@ def broken_barh(xranges, yrange, *, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.cla)
+@docstring.copy(Axes.cla)
 def cla():
     return gca().cla()
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.clabel)
+@docstring.copy(Axes.clabel)
 def clabel(CS, *args, **kwargs):
     return gca().clabel(CS, *args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.cohere)
+@docstring.copy(Axes.cohere)
 def cohere(
         x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         window=mlab.window_hanning, noverlap=0, pad_to=None,
@@ -2497,7 +2489,7 @@ def cohere(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.contour)
+@docstring.copy(Axes.contour)
 def contour(*args, data=None, **kwargs):
     __ret = gca().contour(
         *args, **({"data": data} if data is not None else {}),
@@ -2507,7 +2499,7 @@ def contour(*args, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.contourf)
+@docstring.copy(Axes.contourf)
 def contourf(*args, data=None, **kwargs):
     __ret = gca().contourf(
         *args, **({"data": data} if data is not None else {}),
@@ -2517,7 +2509,7 @@ def contourf(*args, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.csd)
+@docstring.copy(Axes.csd)
 def csd(
         x, y, NFFT=None, Fs=None, Fc=None, detrend=None, window=None,
         noverlap=None, pad_to=None, sides=None, scale_by_freq=None,
@@ -2530,7 +2522,7 @@ def csd(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.errorbar)
+@docstring.copy(Axes.errorbar)
 def errorbar(
         x, y, yerr=None, xerr=None, fmt='', ecolor=None,
         elinewidth=None, capsize=None, barsabove=False, lolims=False,
@@ -2545,7 +2537,7 @@ def errorbar(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.eventplot)
+@docstring.copy(Axes.eventplot)
 def eventplot(
         positions, orientation='horizontal', lineoffsets=1,
         linelengths=1, linewidths=None, colors=None,
@@ -2558,7 +2550,7 @@ def eventplot(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.fill)
+@docstring.copy(Axes.fill)
 def fill(*args, data=None, **kwargs):
     return gca().fill(
         *args, **({"data": data} if data is not None else {}),
@@ -2566,7 +2558,7 @@ def fill(*args, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.fill_between)
+@docstring.copy(Axes.fill_between)
 def fill_between(
         x, y1, y2=0, where=None, interpolate=False, step=None, *,
         data=None, **kwargs):
@@ -2576,7 +2568,7 @@ def fill_between(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.fill_betweenx)
+@docstring.copy(Axes.fill_betweenx)
 def fill_betweenx(
         y, x1, x2=0, where=None, step=None, interpolate=False, *,
         data=None, **kwargs):
@@ -2586,13 +2578,13 @@ def fill_betweenx(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.grid)
+@docstring.copy(Axes.grid)
 def grid(b=None, which='major', axis='both', **kwargs):
     return gca().grid(b=b, which=which, axis=axis, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.hexbin)
+@docstring.copy(Axes.hexbin)
 def hexbin(
         x, y, C=None, gridsize=100, bins=None, xscale='linear',
         yscale='linear', extent=None, cmap=None, norm=None, vmin=None,
@@ -2611,7 +2603,7 @@ def hexbin(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.hist)
+@docstring.copy(Axes.hist)
 def hist(
         x, bins=None, range=None, density=None, weights=None,
         cumulative=False, bottom=None, histtype='bar', align='mid',
@@ -2627,7 +2619,7 @@ def hist(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.hist2d)
+@docstring.copy(Axes.hist2d)
 def hist2d(
         x, y, bins=10, range=None, density=False, weights=None,
         cmin=None, cmax=None, *, data=None, **kwargs):
@@ -2640,7 +2632,7 @@ def hist2d(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.hlines)
+@docstring.copy(Axes.hlines)
 def hlines(
         y, xmin, xmax, colors='k', linestyles='solid', label='', *,
         data=None, **kwargs):
@@ -2651,7 +2643,7 @@ def hlines(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.imshow)
+@docstring.copy(Axes.imshow)
 def imshow(
         X, cmap=None, norm=None, aspect=None, interpolation=None,
         alpha=None, vmin=None, vmax=None, origin=None, extent=None,
@@ -2669,25 +2661,25 @@ def imshow(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.legend)
+@docstring.copy(Axes.legend)
 def legend(*args, **kwargs):
     return gca().legend(*args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.locator_params)
+@docstring.copy(Axes.locator_params)
 def locator_params(axis='both', tight=None, **kwargs):
     return gca().locator_params(axis=axis, tight=tight, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.loglog)
+@docstring.copy(Axes.loglog)
 def loglog(*args, **kwargs):
     return gca().loglog(*args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.magnitude_spectrum)
+@docstring.copy(Axes.magnitude_spectrum)
 def magnitude_spectrum(
         x, Fs=None, Fc=None, window=None, pad_to=None, sides=None,
         scale=None, *, data=None, **kwargs):
@@ -2698,25 +2690,25 @@ def magnitude_spectrum(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.margins)
+@docstring.copy(Axes.margins)
 def margins(*margins, x=None, y=None, tight=True):
     return gca().margins(*margins, x=x, y=y, tight=tight)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.minorticks_off)
+@docstring.copy(Axes.minorticks_off)
 def minorticks_off():
     return gca().minorticks_off()
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.minorticks_on)
+@docstring.copy(Axes.minorticks_on)
 def minorticks_on():
     return gca().minorticks_on()
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.pcolor)
+@docstring.copy(Axes.pcolor)
 def pcolor(
         *args, alpha=None, norm=None, cmap=None, vmin=None,
         vmax=None, data=None, **kwargs):
@@ -2729,7 +2721,7 @@ def pcolor(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.pcolormesh)
+@docstring.copy(Axes.pcolormesh)
 def pcolormesh(
         *args, alpha=None, norm=None, cmap=None, vmin=None,
         vmax=None, shading='flat', antialiased=False, data=None,
@@ -2743,7 +2735,7 @@ def pcolormesh(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.phase_spectrum)
+@docstring.copy(Axes.phase_spectrum)
 def phase_spectrum(
         x, Fs=None, Fc=None, window=None, pad_to=None, sides=None, *,
         data=None, **kwargs):
@@ -2753,7 +2745,7 @@ def phase_spectrum(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.pie)
+@docstring.copy(Axes.pie)
 def pie(
         x, explode=None, labels=None, colors=None, autopct=None,
         pctdistance=0.6, shadow=False, labeldistance=1.1,
@@ -2771,7 +2763,7 @@ def pie(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.plot)
+@docstring.copy(Axes.plot)
 def plot(*args, scalex=True, scaley=True, data=None, **kwargs):
     return gca().plot(
         *args, scalex=scalex, scaley=scaley, **({"data": data} if data
@@ -2779,7 +2771,7 @@ def plot(*args, scalex=True, scaley=True, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.plot_date)
+@docstring.copy(Axes.plot_date)
 def plot_date(
         x, y, fmt='o', tz=None, xdate=True, ydate=False, *,
         data=None, **kwargs):
@@ -2789,7 +2781,7 @@ def plot_date(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.psd)
+@docstring.copy(Axes.psd)
 def psd(
         x, NFFT=None, Fs=None, Fc=None, detrend=None, window=None,
         noverlap=None, pad_to=None, sides=None, scale_by_freq=None,
@@ -2802,7 +2794,7 @@ def psd(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.quiver)
+@docstring.copy(Axes.quiver)
 def quiver(*args, data=None, **kw):
     __ret = gca().quiver(
         *args, **({"data": data} if data is not None else {}), **kw)
@@ -2811,13 +2803,13 @@ def quiver(*args, data=None, **kw):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.quiverkey)
+@docstring.copy(Axes.quiverkey)
 def quiverkey(Q, X, Y, U, label, **kw):
     return gca().quiverkey(Q, X, Y, U, label, **kw)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.scatter)
+@docstring.copy(Axes.scatter)
 def scatter(
         x, y, s=None, c=None, marker=None, cmap=None, norm=None,
         vmin=None, vmax=None, alpha=None, linewidths=None, verts=None,
@@ -2833,19 +2825,19 @@ def scatter(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.semilogx)
+@docstring.copy(Axes.semilogx)
 def semilogx(*args, **kwargs):
     return gca().semilogx(*args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.semilogy)
+@docstring.copy(Axes.semilogy)
 def semilogy(*args, **kwargs):
     return gca().semilogy(*args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.specgram)
+@docstring.copy(Axes.specgram)
 def specgram(
         x, NFFT=None, Fs=None, Fc=None, detrend=None, window=None,
         noverlap=None, cmap=None, xextent=None, pad_to=None,
@@ -2862,7 +2854,7 @@ def specgram(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.spy)
+@docstring.copy(Axes.spy)
 def spy(
         Z, precision=0, marker=None, markersize=None, aspect='equal',
         origin='upper', **kwargs):
@@ -2874,7 +2866,7 @@ def spy(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.stackplot)
+@docstring.copy(Axes.stackplot)
 def stackplot(x, *args, data=None, **kwargs):
     return gca().stackplot(
         x, *args, **({"data": data} if data is not None else {}),
@@ -2882,7 +2874,7 @@ def stackplot(x, *args, data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.stem)
+@docstring.copy(Axes.stem)
 def stem(
         *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
         label=None, data=None):
@@ -2893,7 +2885,7 @@ def stem(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.step)
+@docstring.copy(Axes.step)
 def step(x, y, *args, where='pre', data=None, **kwargs):
     return gca().step(
         x, y, *args, where=where, **({"data": data} if data is not
@@ -2901,7 +2893,7 @@ def step(x, y, *args, where='pre', data=None, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.streamplot)
+@docstring.copy(Axes.streamplot)
 def streamplot(
         x, y, u, v, density=1, linewidth=None, color=None, cmap=None,
         norm=None, arrowsize=1, arrowstyle='-|>', minlength=0.1,
@@ -2920,7 +2912,7 @@ def streamplot(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.table)
+@docstring.copy(Axes.table)
 def table(
         cellText=None, cellColours=None, cellLoc='right',
         colWidths=None, rowLabels=None, rowColours=None,
@@ -2936,19 +2928,19 @@ def table(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.text)
+@docstring.copy(Axes.text)
 def text(x, y, s, fontdict=None, withdash=False, **kwargs):
     return gca().text(x, y, s, fontdict=fontdict, withdash=withdash, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.tick_params)
+@docstring.copy(Axes.tick_params)
 def tick_params(axis='both', **kwargs):
     return gca().tick_params(axis=axis, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.ticklabel_format)
+@docstring.copy(Axes.ticklabel_format)
 def ticklabel_format(
         *, axis='both', style='', scilimits=None, useOffset=None,
         useLocale=None, useMathText=None):
@@ -2959,7 +2951,7 @@ def ticklabel_format(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.tricontour)
+@docstring.copy(Axes.tricontour)
 def tricontour(*args, **kwargs):
     __ret = gca().tricontour(*args, **kwargs)
     if __ret._A is not None: sci(__ret)  # noqa
@@ -2967,7 +2959,7 @@ def tricontour(*args, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.tricontourf)
+@docstring.copy(Axes.tricontourf)
 def tricontourf(*args, **kwargs):
     __ret = gca().tricontourf(*args, **kwargs)
     if __ret._A is not None: sci(__ret)  # noqa
@@ -2975,7 +2967,7 @@ def tricontourf(*args, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@_autogen_docstring(Axes.tripcolor)
+@docstring.copy(Axes.tripcolor)
 def tripcolor(*args, **kwargs):
     __ret = gca().tripcolor(*args, **kwargs)
     sci(__ret)
@@ -2983,13 +2975,13 @@ def tripcolor(*args, **kwargs):
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.triplot)
+@docstring.copy(Axes.triplot)
 def triplot(*args, **kwargs):
     return gca().triplot(*args, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.violinplot)
+@docstring.copy(Axes.violinplot)
 def violinplot(
         dataset, positions=None, vert=True, widths=0.5,
         showmeans=False, showextrema=True, showmedians=False,
@@ -3002,7 +2994,7 @@ def violinplot(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.vlines)
+@docstring.copy(Axes.vlines)
 def vlines(
         x, ymin, ymax, colors='k', linestyles='solid', label='', *,
         data=None, **kwargs):
@@ -3013,7 +3005,7 @@ def vlines(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.xcorr)
+@docstring.copy(Axes.xcorr)
 def xcorr(
         x, y, normed=True, detrend=mlab.detrend_none, usevlines=True,
         maxlags=10, *, data=None, **kwargs):
@@ -3024,40 +3016,40 @@ def xcorr(
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes._sci)
+@docstring.copy(Axes._sci)
 def sci(im):
     return gca()._sci(im)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.set_title)
+@docstring.copy(Axes.set_title)
 def title(label, fontdict=None, loc='center', pad=None, **kwargs):
     return gca().set_title(
         label, fontdict=fontdict, loc=loc, pad=pad, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.set_xlabel)
+@docstring.copy(Axes.set_xlabel)
 def xlabel(xlabel, fontdict=None, labelpad=None, **kwargs):
     return gca().set_xlabel(
         xlabel, fontdict=fontdict, labelpad=labelpad, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.set_ylabel)
+@docstring.copy(Axes.set_ylabel)
 def ylabel(ylabel, fontdict=None, labelpad=None, **kwargs):
     return gca().set_ylabel(
         ylabel, fontdict=fontdict, labelpad=labelpad, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.set_xscale)
+@docstring.copy(Axes.set_xscale)
 def xscale(value, **kwargs):
     return gca().set_xscale(value, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
-@docstring.copy_dedent(Axes.set_yscale)
+@docstring.copy(Axes.set_yscale)
 def yscale(value, **kwargs):
     return gca().set_yscale(value, **kwargs)
 
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
index 157c2d50b2b6..ddd1bcbcd3d2 100644
--- a/lib/matplotlib/scale.py
+++ b/lib/matplotlib/scale.py
@@ -1,3 +1,6 @@
+import inspect
+import textwrap
+
 import numpy as np
 from numpy import ma
 
@@ -668,18 +671,17 @@ def scale_factory(scale, axis, **kwargs):
     """
     Return a scale class by name.
 
-    ACCEPTS: [ %(names)s ]
+    Parameters
+    ----------
+    scale : {%(names)s}
+    axis : Axis
     """
     scale = scale.lower()
-    if scale is None:
-        scale = 'linear'
-
     if scale not in _scale_mapping:
         raise ValueError("Unknown scale type '%s'" % scale)
-
     return _scale_mapping[scale](axis, **kwargs)
-scale_factory.__doc__ = cbook.dedent(scale_factory.__doc__) % \
-    {'names': " | ".join(get_scale_names())}
+scale_factory.__doc__ = scale_factory.__doc__ % {
+    "names": ", ".join(get_scale_names())}
 
 
 def register_scale(scale_class):
@@ -706,15 +708,13 @@ def _get_scale_docs():
     Helper function for generating docstrings related to scales.
     """
     docs = []
-    for name in get_scale_names():
-        scale_class = _scale_mapping[name]
-        docs.append("    '%s'" % name)
-        docs.append("")
-        class_docs = cbook.dedent(scale_class.__init__.__doc__)
-        class_docs = "".join(["        %s\n" %
-                              x for x in class_docs.split("\n")])
-        docs.append(class_docs)
-        docs.append("")
+    for name, scale_class in _scale_mapping.items():
+        docs.extend([
+            f"    {name!r}",
+            "",
+            textwrap.indent(inspect.getdoc(scale_class.__init__), " " * 8),
+            ""
+        ])
     return "\n".join(docs)
 
 
diff --git a/lib/mpl_toolkits/axes_grid1/anchored_artists.py b/lib/mpl_toolkits/axes_grid1/anchored_artists.py
index 949faacb1beb..fef40db2dcb5 100644
--- a/lib/mpl_toolkits/axes_grid1/anchored_artists.py
+++ b/lib/mpl_toolkits/axes_grid1/anchored_artists.py
@@ -10,7 +10,6 @@
 
 
 class AnchoredDrawingArea(AnchoredOffsetbox):
-    @docstring.dedent
     def __init__(self, width, height, xdescent, ydescent,
                  loc, pad=0.4, borderpad=0.5, prop=None, frameon=True,
                  **kwargs):
@@ -87,7 +86,6 @@ def __init__(self, width, height, xdescent, ydescent,
 
 
 class AnchoredAuxTransformBox(AnchoredOffsetbox):
-    @docstring.dedent
     def __init__(self, transform, loc,
                  pad=0.4, borderpad=0.5, prop=None, frameon=True, **kwargs):
         """
@@ -160,7 +158,6 @@ def __init__(self, transform, loc,
 
 
 class AnchoredEllipse(AnchoredOffsetbox):
-    @docstring.dedent
     def __init__(self, transform, width, height, angle, loc,
                  pad=0.1, borderpad=0.1, prop=None, frameon=True, **kwargs):
         """
@@ -226,7 +223,6 @@ def __init__(self, transform, width, height, angle, loc,
 
 
 class AnchoredSizeBar(AnchoredOffsetbox):
-    @docstring.dedent
     def __init__(self, transform, size, label, loc,
                  pad=0.1, borderpad=0.1, sep=2,
                  frameon=True, size_vertical=0, color='black',
@@ -375,7 +371,6 @@ def __init__(self, transform, size, label, loc,
 
 
 class AnchoredDirectionArrows(AnchoredOffsetbox):
-    @docstring.dedent
     def __init__(self, transform, label_x, label_y, length=0.15,
                  fontsize=0.08, loc=2, angle=0, aspect_ratio=1, pad=0.4,
                  borderpad=0.4, frameon=False, color='w', alpha=1,
diff --git a/tools/boilerplate.py b/tools/boilerplate.py
index d7ad65ffb16b..74a3a4d065b8 100644
--- a/tools/boilerplate.py
+++ b/tools/boilerplate.py
@@ -35,7 +35,7 @@
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost."""
 
 CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """
-@_autogen_docstring(Axes.%(real_name)s)
+@docstring.copy(Axes.%(real_name)s)
 def %(func)s%(sig)s:
     __ret = gca().%(real_name)s%(call)s
 %(mappable)s
@@ -43,7 +43,7 @@ def %(func)s%(sig)s:
 """
 
 NON_CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """
-@docstring.copy_dedent(Axes.%(real_name)s)
+@docstring.copy(Axes.%(real_name)s)
 def %(func)s%(sig)s:
     return gca().%(real_name)s%(call)s
 """