diff --git a/doc/_templates/automodule.rst b/doc/_templates/automodule.rst
index 7fa0780eb266..e9f2a755d413 100644
--- a/doc/_templates/automodule.rst
+++ b/doc/_templates/automodule.rst
@@ -1,5 +1,12 @@
 {{ fullname | escape | underline}}
 
+{% if fullname in ['mpl_toolkits.axes_grid1.colorbar'] %}
+.. To prevent problems with the autosummary for the colorbar doc
+   treat this separately (sphinx-doc/sphinx/issues/4874)
+.. automodule:: {{ fullname }}
+   :members:
+   
+{% else %}
 
 .. automodule:: {{ fullname }}
    :no-members:
@@ -33,3 +40,4 @@ Functions
    {{ item }}{% endif %}{% endfor %}
 {% endif %}
 {% endblock %}
+{% endif %}
diff --git a/doc/_templates/autosummary.rst b/doc/_templates/autosummary.rst
index cf000cc16de0..8991f3c9ebc4 100644
--- a/doc/_templates/autosummary.rst
+++ b/doc/_templates/autosummary.rst
@@ -6,11 +6,17 @@
 .. auto{{ objtype }}:: {{ objname }}
 
 {% if objtype in ['class', 'method', 'function'] %}
-
+{% if objname in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
+                      'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
+.. Filter out the above aliases to other classes, as sphinx gallery
+   creates no example file for those (sphinx-gallery/sphinx-gallery#365)
+   
+{% else %}
 .. include:: {{module}}.{{objname}}.examples
 
 .. raw:: html
 
     <div class="clearer"></div>
 
+{% endif %}
 {% endif %}
\ No newline at end of file
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
index 4b83c9660788..6a66a0bc3367 100644
--- a/doc/api/api_changes.rst
+++ b/doc/api/api_changes.rst
@@ -62,7 +62,7 @@ Changed function signatures
 kwarg ``fig`` to `.GridSpec.get_subplot_params` is
 deprecated,  use ``figure`` instead.
 
-Using `.pyplot.axes` with an `.Axes` as argument is deprecated. This sets
+Using `.pyplot.axes` with an `~matplotlib.axes.Axes` as argument is deprecated. This sets
 the current axes, i.e. it has the same effect as `.pyplot.sca`. For clarity
 ``plt.sca(ax)`` should be preferred over ``plt.axes(ax)``.
 
@@ -864,7 +864,7 @@ Deprecation and removal
 
 Color of Axes
 ~~~~~~~~~~~~~
-The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
+The ``axisbg`` and ``axis_bgcolor`` properties on *Axes* have been
 deprecated in favor of ``facecolor``.
 
 GTK and GDK backends deprecated
@@ -1297,8 +1297,8 @@ algorithm that was not necessarily applicable to custom Axes. Three new private
 methods, :meth:`~matplotlib.axes._base._AxesBase._get_view`,
 :meth:`~matplotlib.axes._base._AxesBase._set_view`, and
 :meth:`~matplotlib.axes._base._AxesBase._set_view_from_bbox`, allow for custom
-``Axes`` classes to override the pan and zoom algorithms. Implementors of
-custom ``Axes`` who override these methods may provide suitable behaviour for
+*Axes* classes to override the pan and zoom algorithms. Implementors of
+custom *Axes* who override these methods may provide suitable behaviour for
 both pan and zoom as well as the view navigation buttons on the interactive
 toolbars.
 
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 3cc26c8beb06..78669f992177 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -74,5 +74,8 @@ Toolkits
 .. toctree::
    :maxdepth: 1
 
-   toolkits/axes_grid.rst
+   
    toolkits/mplot3d.rst
+   toolkits/axes_grid1.rst
+   toolkits/axisartist.rst
+   toolkits/axes_grid.rst
diff --git a/doc/api/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst
index ed8692fcc016..991b0ff6813a 100644
--- a/doc/api/toolkits/axes_grid.rst
+++ b/doc/api/toolkits/axes_grid.rst
@@ -1,28 +1,26 @@
 .. _axes_grid-api-index:
 
-####################################
-The Matplotlib axes_grid Toolkit API
-####################################
-
-:Release: |version|
-:Date: |today|
+Matplotlib axes_grid Toolkit
+============================
 
 .. currentmodule:: mpl_toolkits
 
-Axes Grid
----------
+
 .. note::
-   
-   There is an older version of the AxesGrid toolkit, ``axes_grid`` (instead of
-   ``axes_grid1``).  The old version had a single namespace for all axes_grid
-   objects, and in the new version this toolkit was broken
-   into the two modules below. For the documentation on ``axes_grid``,
+   AxesGrid toolkit has been a part of matplotlib since v
+   0.99. Originally, the toolkit had a single namespace of
+   *axes_grid*. In more recent version, the toolkit
+   has divided into two separate namespace (*axes_grid1* and *axisartist*).
+   While *axes_grid* namespace is maintained for the backward compatibility,
+   use of *axes_grid1* and *axisartist* is recommended. 
+   For the documentation on ``axes_grid``,
    see the `previous version of the docs 
    <https://matplotlib.org/2.0.1/mpl_toolkits/axes_grid/index.html#toolkit-axesgrid-index>`_.
 
-.. autosummary::
-   :toctree: ../_as_gen
-   :template: automodule.rst
+.. toctree::
+    :maxdepth: 1
+    
+    axes_grid1
+    axisartist
+
 
-   axes_grid1
-   axisartist
diff --git a/doc/api/toolkits/axes_grid1.rst b/doc/api/toolkits/axes_grid1.rst
new file mode 100644
index 000000000000..52363877e285
--- /dev/null
+++ b/doc/api/toolkits/axes_grid1.rst
@@ -0,0 +1,39 @@
+.. _toolkit_axesgrid1-index:
+
+Matplotlib axes_grid1 Toolkit
+=============================
+
+The matplotlib :class:`mpl_toolkits.axes_grid1` toolkit is a collection of
+helper classes to ease displaying multiple images in matplotlib.  While the
+aspect parameter in matplotlib adjust the position of the single axes,
+axes_grid1 toolkit provides a framework to adjust the position of
+multiple axes according to their aspects.
+
+See :ref:`axes_grid1_users-guide-index` for a guide on the usage of axes_grid1.
+
+.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png
+   :target: ../../gallery/axes_grid1/demo_axes_grid.html
+   :align: center
+   :scale: 50
+
+
+
+.. currentmodule:: mpl_toolkits
+
+**The submodules of the axes_grid1 API are:**
+
+.. autosummary::
+   :toctree: ../_as_gen
+   :template: automodule.rst
+
+   axes_grid1.anchored_artists
+   axes_grid1.axes_divider
+   axes_grid1.axes_grid
+   axes_grid1.axes_rgb
+   axes_grid1.axes_size
+   axes_grid1.colorbar
+   axes_grid1.inset_locator
+   axes_grid1.mpl_axes
+   axes_grid1.parasite_axes
+
+
diff --git a/doc/api/toolkits/axisartist.rst b/doc/api/toolkits/axisartist.rst
new file mode 100644
index 000000000000..a08113f71396
--- /dev/null
+++ b/doc/api/toolkits/axisartist.rst
@@ -0,0 +1,40 @@
+.. _toolkit_axisartist-index:
+
+Matplotlib axisartist Toolkit
+=============================
+
+The *axisartist* namespace includes a derived Axes implementation (
+:class:`mpl_toolkits.axisartist.Axes`). The
+biggest difference is that the artists that are responsible for drawing
+axis lines, ticks, ticklabels, and axis labels are separated out from the
+mpl's Axis class. This change was strongly motivated to support curvilinear grid.
+
+You can find a tutorial describing usage of axisartist at the 
+:ref:`axisartist_users-guide-index` user guide.
+
+.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png
+   :target: ../../gallery/axisartist/demo_curvelinear_grid.html
+   :align: center
+   :scale: 50
+
+.. currentmodule:: mpl_toolkits
+
+**The submodules of the axisartist API are:**
+
+.. autosummary::
+   :toctree: ../_as_gen
+   :template: automodule.rst
+
+   axisartist.angle_helper
+   axisartist.axes_divider
+   axisartist.axes_grid
+   axisartist.axes_rgb
+   axisartist.axis_artist
+   axisartist.axisline_style
+   axisartist.axislines
+   axisartist.clip_path
+   axisartist.floating_axes
+   axisartist.grid_finder
+   axisartist.grid_helper_curvelinear
+   axisartist.parasite_axes
+
diff --git a/doc/mpl_toolkits/index.rst b/doc/api/toolkits/index.rst
similarity index 51%
rename from doc/mpl_toolkits/index.rst
rename to doc/api/toolkits/index.rst
index 285f9d49295a..f995dfb3b54d 100644
--- a/doc/mpl_toolkits/index.rst
+++ b/doc/api/toolkits/index.rst
@@ -24,8 +24,8 @@ lighter weight solution for some use cases. Check out the
 :ref:`mplot3d tutorial <sphx_glr_tutorials_toolkits_mplot3d.py>` for more
 information.
 
-.. figure:: ../gallery/mplot3d/images/sphx_glr_contourf3d_2_001.png
-   :target: ../gallery/mplot3d/contourf3d_2.html
+.. figure:: ../../gallery/mplot3d/images/sphx_glr_contourf3d_2_001.png
+   :target: ../../gallery/mplot3d/contourf3d_2.html
    :align: center
    :scale: 50
 
@@ -41,37 +41,20 @@ Links
 -----
 * mpl3d API: :ref:`toolkit_mplot3d-api`
 
-.. _toolkit_axes_grid1:
+.. _toolkit_axes_grid1_incl:
 
-axes_grid1
-==========
+.. include:: axes_grid1.rst
+   :start-line: 1
 
-The :mod:`mpl_toolkits.axes_grid1` toolkit is a
-collection of helper classes for displaying multiple axes in Matplotlib.
+.. _toolkit_axisartist_incl:
+   
+.. include:: axisartist.rst
+   :start-line: 1
 
-.. image:: /_static/demo_axes_grid.png
-
-.. toctree::
-    :maxdepth: 2
-
-    axes_grid1/index.rst
-
-
-.. _toolkit_axisartist:
-
-axisartist
-==========
-
-The :mod:`mpl_toolkits.axisartist` toolkit contains
-a custom Axes class that is meant to support curvilinear grids.
-
-.. toctree::
-    :maxdepth: 2
-
-    axisartist/index.rst
+.. _toolkit_axes_grid_incl:
+   
+.. include:: axes_grid.rst
+   :start-line: 1
 
 
-API
----
-* Axes Grid and Axis Artist API: :ref:`axes_grid-api-index`
 
diff --git a/doc/mpl_toolkits/mplot3d/faq.rst b/doc/api/toolkits/mplot3d/faq.rst
similarity index 100%
rename from doc/mpl_toolkits/mplot3d/faq.rst
rename to doc/api/toolkits/mplot3d/faq.rst
diff --git a/doc/mpl_toolkits/mplot3d/index.rst b/doc/api/toolkits/mplot3d/index.rst
similarity index 95%
rename from doc/mpl_toolkits/mplot3d/index.rst
rename to doc/api/toolkits/mplot3d/index.rst
index 22d2368912e9..b5ec1418deec 100644
--- a/doc/mpl_toolkits/mplot3d/index.rst
+++ b/doc/api/toolkits/mplot3d/index.rst
@@ -14,7 +14,7 @@ The resulting graph will have the same look and feel as regular 2D plots.
 See the :ref:`mplot3d tutorial <sphx_glr_tutorials_toolkits_mplot3d.py>` for
 more information on how to use this toolkit.
 
-.. image:: ../../_static/demo_mplot3d.png
+.. image:: /_static/demo_mplot3d.png
 
 The interactive backends also provide the ability to rotate and zoom
 the 3D scene. One can rotate the 3D scene by simply clicking-and-dragging
diff --git a/doc/contents.rst b/doc/contents.rst
index 72612f7b7694..104e143a07c2 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -16,7 +16,7 @@ Overview
 
    users/index.rst
    faq/index.rst
-   mpl_toolkits/index.rst
+   api/toolkits/index.rst
    resources/index.rst
    thirdpartypackages/index.rst
    api/index.rst
diff --git a/doc/index.rst b/doc/index.rst
index b5eb92d8534f..fa9c101ab2c2 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -142,7 +142,7 @@ require changes to your existing code is logged in the :doc:`API changes
 Toolkits
 ========
 
-Matplotlib ships with several add-on :doc:`toolkits <mpl_toolkits/index>`,
+Matplotlib ships with several add-on :doc:`toolkits <api/toolkits/index>`,
 including 3d plotting with `mplot3d`, axes helpers in `axes_grid1` and axis
 helpers in `axisartist`.
 
diff --git a/doc/mpl_toolkits/axes_grid1/index.rst b/doc/mpl_toolkits/axes_grid1/index.rst
deleted file mode 100644
index aacb1cc5b872..000000000000
--- a/doc/mpl_toolkits/axes_grid1/index.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-
-.. _toolkit_axesgrid1-index:
-
-Matplotlib axes_grid1 Toolkit
-=============================
-
-The matplotlib :class:`mpl_toolkits.axes_grid1` toolkit is a collection of
-helper classes to ease displaying multiple images in matplotlib.  While the
-aspect parameter in matplotlib adjust the position of the single axes,
-axesgrid1 toolkit provides a framework to adjust the position of
-multiple axes according to their aspects.
-
-See :ref:`axes_grid1_users-guide-index` for a guide on the usage of axes_grid1.
-
-
-.. image:: ../../_static/demo_axes_grid.png
-
-.. note::
-   AxesGrid toolkit has been a part of matplotlib since v
-   0.99. Originally, the toolkit had a single namespace of
-   *axes_grid*. In more recent version, the toolkit
-   has divided into two separate namespace (*axes_grid1* and *axisartist*).
-   While *axes_grid* namespace is maintained for the backward compatibility,
-   use of *axes_grid1* and *axisartist* is recommended.
diff --git a/doc/mpl_toolkits/axisartist/index.rst b/doc/mpl_toolkits/axisartist/index.rst
deleted file mode 100644
index 2a46936f1381..000000000000
--- a/doc/mpl_toolkits/axisartist/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _toolkit_axisartist-index:
-
-Matplotlib axisartist Toolkit
-=============================
-
-The *axisartist* namespace includes a derived Axes implementation (
-:class:`mpl_toolkits.axisartist.Axes`). The
-biggest difference is that the artists that are responsible for drawing
-axis lines, ticks, ticklabels, and axis labels are separated out from the
-mpl's Axis class. This change was strongly motivated to support curvilinear grid.
-
-You can find a tutorial describing usage of axisartist at
-:ref:`axisartist_users-guide-index`.
diff --git a/examples/ticks_and_spines/date_index_formatter.py b/examples/ticks_and_spines/date_index_formatter2.py
similarity index 100%
rename from examples/ticks_and_spines/date_index_formatter.py
rename to examples/ticks_and_spines/date_index_formatter2.py
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
index d5fd7c22f321..820fb7724f0e 100644
--- a/lib/matplotlib/contour.py
+++ b/lib/matplotlib/contour.py
@@ -738,7 +738,7 @@ class ContourSet(cm.ScalarMappable, ContourLabeler):
     """
     Store a set of contour lines or filled regions.
 
-    User-callable method: `~.Axes.clabel`
+    User-callable method: `~.axes.Axes.clabel`
 
     Parameters
     ----------
@@ -773,7 +773,7 @@ class ContourSet(cm.ScalarMappable, ContourLabeler):
 
     kwargs :
         Keyword arguments are as described in the docstring of
-        `~.Axes.contour`.
+        `~.axes.Axes.contour`.
 
     Attributes
     ----------
@@ -803,7 +803,7 @@ def __init__(self, ax, *args, **kwargs):
         Parameters
         ----------
         ax :
-            The `.Axes` object to draw on.
+            The `~.axes.Axes` object to draw on.
 
         levels : [level0, level1, ..., leveln]
             A list of floating point numbers indicating the contour
@@ -834,7 +834,7 @@ def __init__(self, ax, *args, **kwargs):
 
         **kwargs
             Keyword arguments are as described in the docstring of
-            `~.Axes.contour`.
+            `~axes.Axes.contour`.
         """
         self.ax = ax
         self.levels = kwargs.pop('levels', None)
@@ -1436,7 +1436,7 @@ class QuadContourSet(ContourSet):
     """
     Create and store a set of contour lines or filled regions.
 
-    User-callable method: `~.Axes.clabel`
+    User-callable method: `~axes.Axes.clabel`
 
     Attributes
     ----------
@@ -1755,7 +1755,7 @@ def _initialize_x_y(self, z):
         locator : ticker.Locator subclass, optional
             The locator is used to determine the contour levels if they
             are not given explicitly via *levels*.
-            Defaults to `.MaxNLocator`.
+            Defaults to `~.ticker.MaxNLocator`.
 
         extend : {'neither', 'both', 'min', 'max'}, optional
             Unless this is 'neither', contour levels are automatically
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 8fdea9c13b04..da1d07d91c36 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -58,8 +58,9 @@ def _stale_figure_callback(self, val):
 
 class AxesStack(Stack):
     """
-    Specialization of the `.Stack` to handle all tracking of `.Axes` in a
-    `.Figure`. This stack stores ``key, (ind, axes)`` pairs, where:
+    Specialization of the `.Stack` to handle all tracking of
+    `~matplotlib.axes.Axes` in a `.Figure`.
+    This stack stores ``key, (ind, axes)`` pairs, where:
 
         * **key** should be a hash of the args and kwargs
           used in generating the Axes.
@@ -991,7 +992,8 @@ def set_frameon(self, b):
 
     def delaxes(self, ax):
         """
-        Remove the `.Axes` *ax* from the figure and update the current axes.
+        Remove the `~matplotlib.axes.Axes` *ax* from the figure and update the
+        current axes.
         """
         self._axstack.remove(ax)
         for func in self._axobservers:
@@ -2110,7 +2112,8 @@ def align_xlabels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list of (or ndarray) `.Axes` to align the xlabels.
+            Optional list of (or ndarray) `~matplotlib.axes.Axes`
+            to align the xlabels.
             Default is to align all axes on the figure.
 
         See Also
@@ -2178,7 +2181,8 @@ def align_ylabels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list (or ndarray) of `.Axes` to align the ylabels.
+            Optional list (or ndarray) of `~matplotlib.axes.Axes`
+            to align the ylabels.
             Default is to align all axes on the figure.
 
         See Also
@@ -2241,7 +2245,8 @@ def align_labels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list (or ndarray) of `.Axes` to align the labels.
+            Optional list (or ndarray) of `~matplotlib.axes.Axes`
+            to align the labels.
             Default is to align all axes on the figure.
 
         See Also
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
index c345a31f1940..585915e0c554 100644
--- a/lib/matplotlib/legend.py
+++ b/lib/matplotlib/legend.py
@@ -346,7 +346,7 @@ def __init__(self, parent, handles, labels,
         """
         Parameters
         ----------
-        parent : `.Axes` or `.Figure`
+        parent : `~matplotlib.axes.Axes` or `.Figure`
             The artist that contains the legend.
 
         handles : sequence of `.Artist`
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index cbb4ebe59e6f..fc99fb6085db 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -782,9 +782,9 @@ def axes(arg=None, **kwargs):
         - 4-tuple of floats *rect* = ``[left, bottom, width, height]``.
           A new axes is added with dimensions *rect* in normalized
           (0, 1) units using `~.Figure.add_axes` on the current figure.
-        - `.Axes`: This is equivalent to `.pyplot.sca`. It sets the current
-          axes to *arg*. Note: This implicitly changes the current figure to
-          the parent of *arg*.
+        - `~matplotlib.axes.Axes`: This is equivalent to `.pyplot.sca`.
+          It sets the current axes to *arg*. Note: This implicitly
+          changes the current figure to the parent of *arg*.
 
           .. note:: The use of an Axes as an argument is deprecated and will be
                     removed in v3.0. Please use `.pyplot.sca` instead.
@@ -898,16 +898,16 @@ def subplot(*args, **kwargs):
 
        subplot(nrows, ncols, index, **kwargs)
 
-    In the current figure, create and return an `.Axes`, at position *index*
-    of a (virtual) grid of *nrows* by *ncols* axes.  Indexes go from 1 to
-    ``nrows * ncols``, incrementing in row-major order.
+    In the current figure, create and return an `~matplotlib.axes.Axes`,
+    at position *index* of a (virtual) grid of *nrows* by *ncols* axes.
+    Indexes go from 1 to ``nrows * ncols``, incrementing in row-major order.
 
     If *nrows*, *ncols* and *index* are all less than 10, they can also be
     given as a single, concatenated, three-digit number.
 
     For example, ``subplot(2, 3, 3)`` and ``subplot(233)`` both create an
-    `.Axes` at the top right corner of the current figure, occupying half of
-    the figure height and a third of the figure width.
+    `matplotlib.axes.Axes` at the top right corner of the current figure,
+    occupying half of the figure height and a third of the figure width.
 
     .. note::
 
diff --git a/lib/mpl_toolkits/axes_grid1/colorbar.py b/lib/mpl_toolkits/axes_grid1/colorbar.py
index 65dc20c78d1b..3a76914a6fb3 100644
--- a/lib/mpl_toolkits/axes_grid1/colorbar.py
+++ b/lib/mpl_toolkits/axes_grid1/colorbar.py
@@ -1,4 +1,4 @@
-'''
+"""
 Colorbar toolkit with two classes and a function:
 
     :class:`ColorbarBase`
@@ -16,8 +16,8 @@
 The :meth:`~matplotlib.figure.Figure.colorbar` method uses :func:`make_axes`
 and :class:`Colorbar`; the :func:`~matplotlib.pyplot.colorbar` function
 is a thin wrapper over :meth:`~matplotlib.figure.Figure.colorbar`.
+"""
 
-'''
 import six
 from six.moves import xrange, zip
 
@@ -129,9 +129,9 @@
 Additional keyword arguments are of two kinds:
 
   axes properties:
-%s
+    %s
   colorbar properties:
-%s
+    %s
 
 If *mappable* is a :class:`~matplotlib.contours.ContourSet`, its *extend*
 kwarg is included automatically.
@@ -172,7 +172,7 @@
 unconventional value is to prevent underflow when log scale is used.
 ''' % (make_axes_kw_doc, colormap_kw_doc)
 
-docstring.interpd.update(colorbar_doc=colorbar_doc)
+#docstring.interpd.update(colorbar_doc=colorbar_doc)
 
 
 class CbarAxesLocator(object):
@@ -756,7 +756,9 @@ def update_bruteforce(self, mappable):
 def make_axes(parent, **kw):
     '''
     Resize and reposition a parent axes, and return a child
-    axes suitable for a colorbar::
+    axes suitable for a colorbar
+
+    ::
 
         cax, kw = make_axes(parent, **kw)
 
@@ -798,13 +800,14 @@ def make_axes(parent, **kw):
     cax.set_aspect(aspect, anchor=anchor, adjustable='box')
     return cax, kw
 
-
+@docstring.Substitution(colorbar_doc)
 def colorbar(mappable, cax=None, ax=None, **kw):
     """
     Create a colorbar for a ScalarMappable instance.
 
     Documentation for the pylab thin wrapper:
-    %(colorbar_doc)s
+
+    %s
     """
     import matplotlib.pyplot as plt
     if ax is None:
diff --git a/lib/mpl_toolkits/axisartist/axis_artist.py b/lib/mpl_toolkits/axisartist/axis_artist.py
index e67036bc2a5c..0cf14608d8ec 100644
--- a/lib/mpl_toolkits/axisartist/axis_artist.py
+++ b/lib/mpl_toolkits/axisartist/axis_artist.py
@@ -59,7 +59,7 @@
 The text angles are actually relative to (90 + angle of the direction
 to the ticklabel), which gives 0 for bottom axis.
 
-                        left bottom right top
+ Parameter              left bottom right top
  ticklabels location    left right  right left
  axislabel location     left right  right left
  ticklabels angle       90    0      -90  180
@@ -83,6 +83,7 @@
  * AxisLabel : pad
 
 """
+
 import six
 
 # FIXME :
diff --git a/lib/mpl_toolkits/axisartist/floating_axes.py b/lib/mpl_toolkits/axisartist/floating_axes.py
index dbe1d700e924..2f3a6aeec405 100644
--- a/lib/mpl_toolkits/axisartist/floating_axes.py
+++ b/lib/mpl_toolkits/axisartist/floating_axes.py
@@ -233,7 +233,7 @@ def __init__(self, aux_trans, extremes,
         objects which defines the transform and its inverse. The callables
         need take two arguments of array of source coordinates and
         should return two target coordinates:
-          e.g., x2, y2 = trans(x1, y1)
+        e.g., *x2, y2 = trans(x1, y1)*
         """
 
         self._old_values = None
diff --git a/tutorials/advanced/transforms_tutorial.py b/tutorials/advanced/transforms_tutorial.py
index 8d090ae3e62a..409991faf6d2 100644
--- a/tutorials/advanced/transforms_tutorial.py
+++ b/tutorials/advanced/transforms_tutorial.py
@@ -25,9 +25,9 @@
 |           |                             |controlled by xlim and ylim.       |
 +-----------+-----------------------------+-----------------------------------+
 |"axes"     |``ax.transAxes``             |The coordinate system of the       |
-|           |                             |`.Axes`; (0, 0) is bottom left of  |
-|           |                             |the axes, and (1, 1) is top right  |
-|           |                             |of the axes.                       |
+|           |                             |`~matplotlib.axes.Axes`; (0, 0)    |
+|           |                             |is bottom left of the axes, and    |
+|           |                             |(1, 1) is top right of the axes.   |
 +-----------+-----------------------------+-----------------------------------+
 |"figure"   |``fig.transFigure``          |The coordinate system of the       |
 |           |                             |`.Figure`; (0, 0) is bottom left   |
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
index b6f927b6f118..3f32968105c5 100644
--- a/tutorials/intermediate/constrainedlayout_guide.py
+++ b/tutorials/intermediate/constrainedlayout_guide.py
@@ -543,10 +543,11 @@ def docomplicated(suptitle=None):
 # Each item has a layoutbox associated with it. The nesting of gridspecs
 # created with `.GridSpecFromSubplotSpec` can be arbitrarily deep.
 #
-# Each `.Axes` has *two* layoutboxes.  The first one ``ax._layoutbox``
-# represents the outside of the Axes and all its decorations (i.e. ticklabels,
-# axis labels, etc.).  The second layoutbox corresponds to the Axes'
-# `ax.position`, which sets where in the figure the spines are placed.
+# Each ``~matplotlib.axes.Axes` has *two* layoutboxes.  The first one,
+# ``ax._layoutbox`` represents the outside of the Axes and all its
+# decorations (i.e. ticklabels,axis labels, etc.).
+# The second layoutbox corresponds to the Axes' `ax.position`, which sets
+# where in the figure the spines are placed.
 #
 # Why so many stacked containers?  Ideally, all that would be needed are the
 # Axes layout boxes. For the Gridspec case, a container is
@@ -625,10 +626,11 @@ def docomplicated(suptitle=None):
 # constraint on their widths because their subplotspecs occupy the same
 # number of columns (one in this example).
 #
-# The colorbar layout logic is contained in `~.colorbar.make_axes` which
-# call `._constrained_layout.layoutcolorbarsingle` for cbars attached to
-# a single axes, and `._constrained_layout.layoutcolorbargridspec` if the
-# colorbar is associated wiht a gridspec.
+# The colorbar layout logic is contained in `~matplotlib.colorbar.make_axes`
+# which calls `._constrained_layout.layoutcolorbarsingle`
+# for cbars attached to a single axes, and
+# `._constrained_layout.layoutcolorbargridspec` if the colorbar is associated
+# with a gridspec.
 
 fig, ax = plt.subplots(1, 2, constrained_layout=True)
 im = ax[0].pcolormesh(arr, **pc_kwargs)
diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
index ccf3911e65d0..f29e8880e850 100644
--- a/tutorials/text/text_intro.py
+++ b/tutorials/text/text_intro.py
@@ -38,17 +38,20 @@
 `.pyplot` API       OO API              description
 =================== =================== ======================================
 `~.pyplot.text`     `~.Axes.text`       Add text at an arbitrary location of
-                                        the `.Axes`.
+                                        the `~matplotlib.axes.Axes`.
 
 `~.pyplot.annotate` `~.Axes.annotate`   Add an annotation, with an optional
                                         arrow, at an arbitrary location of the
-                                        `.Axes`.
+                                        `~matplotlib.axes.Axes`.
 
-`~.pyplot.xlabel`   `~.Axes.set_xlabel` Add a label to the `.Axes`\\'s x-axis.
+`~.pyplot.xlabel`   `~.Axes.set_xlabel` Add a label to the
+                                        `~matplotlib.axes.Axes`\\'s x-axis.
 
-`~.pyplot.ylabel`   `~.Axes.set_ylabel` Add a label to the `.Axes`\\'s y-axis.
+`~.pyplot.ylabel`   `~.Axes.set_ylabel` Add a label to the
+                                        `~matplotlib.axes.Axes`\\'s y-axis.
 
-`~.pyplot.title`    `~.Axes.set_title`  Add a title to the `.Axes`.
+`~.pyplot.title`    `~.Axes.set_title`  Add a title to the
+                                        `~matplotlib.axes.Axes`.
 
 `~.pyplot.figtext`  `~.Figure.text`     Add text at an arbitrary location of
                                         the `.Figure`.