From 162f68835f95bafcdaa9ad7338e77add599166db Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sun, 5 Sep 2021 21:24:07 +0200 Subject: [PATCH] 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. --- doc/api/index.rst | 15 ---------- doc/api/toolkits/index.rst | 46 ------------------------------ doc/api/toolkits/mplot3d.rst | 32 ++++++++++++++++++--- doc/api/toolkits/mplot3d/index.rst | 28 ------------------ doc/devel/testing.rst | 2 +- doc/index.rst | 2 -- 6 files changed, 29 insertions(+), 96 deletions(-) delete mode 100644 doc/api/toolkits/index.rst delete mode 100644 doc/api/toolkits/mplot3d/index.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 9c33f38ad6d8..ed0e7f310275 100644 --- 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 deleted file mode 100644 index 59c01ab21a69..000000000000 --- a/doc/api/toolkits/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _toolkits-index: - -.. _toolkits: - -######## -Toolkits -######## - -Toolkits are collections of application-specific functions that extend -Matplotlib. - -.. _toolkit_mplot3d: - -mplot3d -======= - -:mod:`mpl_toolkits.mplot3d` provides some basic 3D -plotting (scatter, surf, line, mesh) tools. 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. Check out the -:doc:`mplot3d tutorial ` for more -information. - -.. figure:: ../../gallery/mplot3d/images/sphx_glr_contourf3d_2_001.png - :target: ../../gallery/mplot3d/contourf3d_2.html - :align: center - :scale: 50 - -.. toctree:: - :maxdepth: 2 - - mplot3d/index.rst - mplot3d/faq.rst - -Links ------ -* mpl3d API: :ref:`toolkit_mplot3d-api` - -.. include:: axes_grid1.rst - :start-line: 1 - -.. include:: axisartist.rst - :start-line: 1 - -.. include:: axes_grid.rst - :start-line: 1 diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index 97d3bf13246f..5b3cb52571bb 100644 --- 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 ` 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 deleted file mode 100644 index 8b153c06903f..000000000000 --- a/doc/api/toolkits/mplot3d/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _toolkit_mplot3d-index: -.. currentmodule:: mpl_toolkits.mplot3d - -******* -mplot3d -******* - -Matplotlib mplot3d toolkit -========================== -The mplot3d toolkit adds simple 3D plotting capabilities 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. - -See the :doc:`mplot3d tutorial ` for -more information on how to use this toolkit. - -.. 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 -the scene. Zooming is done by right-clicking the scene and dragging the -mouse up and down. Note that one does not use the zoom button like one -would use for regular 2D plots. - -.. toctree:: - :maxdepth: 2 - - faq.rst diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index aa189948003c..65898b95ee0c 100644 --- 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 index 0350a1047a9f..3b18def1db3c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -31,8 +31,6 @@ Reference - :doc:`Axes API ` for *most* plotting methods - :doc:`Figure API ` for figure-level methods -- :doc:`Extra Toolkits ` - How-tos =======