Merge pull request #21011 from meeseeksmachine/auto-backport-of-pr-21003-on-v3.5.x

dstansby · web-flow · commit 1445af5b4c29 · 2021-09-07T19:05:57.000+01:00
Backport PR #21003 on branch v3.5.x (Deemphasize mpl_toolkits in API docs.)
diff --git a/doc/api/index.rst b/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
diff --git a/doc/api/toolkits/index.rst b/doc/api/toolkits/index.rst
diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.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
diff --git a/doc/api/toolkits/mplot3d/index.rst b/doc/api/toolkits/mplot3d/index.rst
diff --git a/doc/devel/testing.rst b/doc/devel/testing.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
 ^^^^^^^^^^^^^
diff --git a/doc/index.rst b/doc/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
 =======
 
