matplotlib · jklymak · Aug 6, 2018 · Apr 22, 2018 · Apr 28, 2018 · Mar 3, 2018
diff --git 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
@@ -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 %}
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 → doc/api/toolkits/index.rst b/doc/mpl_toolkits/index.rst → doc/api/toolkits/index.rst
@@ -24,8 +24,8 @@ lighter weight solution for some use cases. Check out the
 :doc:`mplot3d tutorial </tutorials/toolkits/mplot3d>` 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 → doc/api/toolkits/mplot3d/faq.rst b/doc/mpl_toolkits/mplot3d/faq.rst → doc/api/toolkits/mplot3d/faq.rst
diff --git a/doc/mpl_toolkits/mplot3d/index.rst → doc/api/toolkits/mplot3d/index.rst b/doc/mpl_toolkits/mplot3d/index.rst → 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 :doc:`mplot3d tutorial </tutorials/toolkits/mplot3d>` 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
@@ -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
@@ -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
diff --git a/doc/mpl_toolkits/axisartist/index.rst b/doc/mpl_toolkits/axisartist/index.rst