Deemphasize mpl_toolkits in API docs.

The docs should present mpl_toolkits as more or less regular modules,
that just happen to live in a different toplevel package for historical
reasons.  So just concatenate them to the end of the main module list.
(This is particularly in preparation of the new website redesign, where
the separate "Extra Toolkits" grouping is really too conspicuous on the
front page.)

Remove the toolkits/index page (documenting mplot3d and
axis_grid/axisartist ("ag/aa") together doesn't make much sense except
for this historical grouping), merging the mplot3d intro blurb together
with the one previously at mplot3d/index.rst; the ag/aa blurbs were
just included from the ag/aa API docs themselves and therefore don't
need to be kept.

The mplot3d intro blurb itself can go to the top of the mplot3d API
docs, rather than needing a separate page.

Author: anntzer

doc/api/index.rst

@@ -101,21 +101,6 @@ Alphabetical list of modules:
    widgets_api.rst
    _api_api.rst
    _enums_api.rst
-
-Toolkits
---------
-
-:ref:`toolkits-index` are collections of application-specific functions that extend
-Matplotlib. The following toolkits are included:
-
-.. toctree::
-   :hidden:
-
-   toolkits/index.rst
-
-.. toctree::
-   :maxdepth: 1
-
    toolkits/mplot3d.rst
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst

doc/api/toolkits/index.rst

@@ -1,8 +1,32 @@
-.. _toolkit_mplot3d-api:
+.. _toolkit_mplot3d-index:
+.. currentmodule:: mpl_toolkits.mplot3d
+
+************************
+``mpl_toolkits.mplot3d``
+************************
+
+The mplot3d toolkit adds simple 3D plotting capabilities (scatter, surface,
+line, mesh, etc.) to Matplotlib by supplying an Axes object that can create
+a 2D projection of a 3D scene.  The resulting graph will have the same look
+and feel as regular 2D plots.  Not the fastest or most feature complete 3D
+library out there, but it ships with Matplotlib and thus may be a lighter
+weight solution for some use cases.
+
+See the :doc:`mplot3d tutorial </tutorials/toolkits/mplot3d>` for
+more information.
+
+.. image:: /_static/demo_mplot3d.png
+   :align: center
+
+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 the scene.
+Zooming is done by right-clicking the scene and dragging the mouse up and down
+(unlike 2D plots, the toolbar zoom button is not used).
+
+.. toctree::
+   :maxdepth: 2
 
-***********
-mplot3d API
-***********
+   mplot3d/faq.rst
 
 .. note::
    `.pyplot` cannot be used to add content to 3D plots, because its function

doc/api/toolkits/mplot3d.rst

@@ -244,7 +244,7 @@ The correct target folder can be found using::
     python -c "import matplotlib.tests; print(matplotlib.tests.__file__.rsplit('/', 1)[0])"
 
 An analogous copying of :file:`lib/mpl_toolkits/tests/baseline_images`
-is necessary for testing the :ref:`toolkits`.
+is necessary for testing ``mpl_toolkits``.
 
 Run the tests
 ^^^^^^^^^^^^^

doc/api/toolkits/mplot3d/index.rst

@@ -31,8 +31,6 @@ Reference
   - :doc:`Axes API <api/axes_api>` for *most* plotting methods
   - :doc:`Figure API <api/figure_api>` for figure-level methods
 
-- :doc:`Extra Toolkits <api/toolkits/index>`
-
 How-tos
 =======