From f407aecd10837c4787c2df953f8ab41a3d837f23 Mon Sep 17 00:00:00 2001
From: Thomas A Caswell <tcaswell@gmail.com>
Date: Mon, 19 Jan 2015 18:53:28 -0500
Subject: [PATCH] DOC : tweak how toolkits docs are organized

Trying to make detailed documentation of mplot3D and axes_gird
more discoverable.
---
 doc/mpl_toolkits/index.rst | 112 +++++++++++++++++++++++--------------
 1 file changed, 69 insertions(+), 43 deletions(-)

diff --git a/doc/mpl_toolkits/index.rst b/doc/mpl_toolkits/index.rst
index 680e970b86e7..fdacf4ce15ca 100644
--- a/doc/mpl_toolkits/index.rst
+++ b/doc/mpl_toolkits/index.rst
@@ -6,20 +6,24 @@
    axes_grid/index.rst
    mplot3d/index.rst
 
+.. _toolkits:
 
 ########
 Toolkits
 ########
 
-.. htmlonly::
-
-   :Release: |version|
-   :Date: |today|
 
-.. _toolkits:
 
 Toolkits are collections of application-specific functions that extend matplotlib.
 
+
+.. _toolkits-mapping:
+
+
+Mapping Toolkits
+****************
+
+
 .. _toolkit_basemap:
 
 Basemap
@@ -50,43 +54,21 @@ tools. An example plot from the
     :height: 400px
 
 
-.. _toolkit_gtk:
-
-GTK Tools
-=========
-
-mpl_toolkits.gtktools provides some utilities for working with GTK.
-This toolkit ships with matplotlib, but requires `pygtk
-<http://www.pygtk.org/>`_.
-
-
-.. _toolkit_excel:
-
-Excel Tools
-===========
-
-mpl_toolkits.exceltools provides some utilities for working with
-Excel.  This toolkit ships with matplotlib, but requires
-`xlwt <http://pypi.python.org/pypi/xlwt>`_
-
-
-.. _toolkit_natgrid:
-
-Natgrid
-=======
-(*Not distributed with matplotlib*)
+.. _toolkits-shipped:
 
-mpl_toolkits.natgrid is an interface to natgrid C library for gridding
-irregularly spaced data.  This requires a separate installation of the
-natgrid toolkit from the sourceforge `download
-<http://sourceforge.net/project/showfiles.php?group_id=80706&package_id=142792>`_
-page.
 
+General Toolkits
+****************
 
 .. _toolkit_mplot3d:
 
 mplot3d
 =======
+.. toctree::
+   :maxdepth: 2
+
+   mplot3d/index
+
 
 :ref:`mpl_toolkits.mplot3d <toolkit_mplot3d-index>` provides some basic 3D plotting (scatter, surf,
 line, mesh) tools.  Not the fastest or feature complete 3D library out
@@ -99,13 +81,21 @@ solution for some use cases.
 
 AxesGrid
 ========
+.. toctree::
+   :maxdepth: 2
+
+   axes_grid/index
+
 
 The matplotlib :ref:`AxesGrid <toolkit_axesgrid-index>` toolkit is a collection of helper classes to
 ease displaying multiple images in matplotlib. The AxesGrid toolkit is
 distributed with matplotlib source.
 
+
+
 .. image:: /_static/demo_axes_grid.png
 
+
 .. _toolkit_mpldatacursor:
 
 MplDataCursor
@@ -116,19 +106,44 @@ MplDataCursor
 toolkit written by Joe Kington to provide interactive "data cursors"
 (clickable annotation boxes) for matplotlib.
 
-.. _toolkit_prettyplotlib:
 
-prettyplotlib
-=============
-`prettyplotlib <https://olgabot.github.io/prettyplotlib>`_ is an extension
-to matplotlib which changes many of the defaults to make plots some
-consider more attractive.
+.. _toolkit_gtk:
+
+GTK Tools
+=========
+
+mpl_toolkits.gtktools provides some utilities for working with GTK.
+This toolkit ships with matplotlib, but requires `pygtk
+<http://www.pygtk.org/>`_.
+
+
+.. _toolkit_excel:
+
+Excel Tools
+===========
+
+mpl_toolkits.exceltools provides some utilities for working with
+Excel.  This toolkit ships with matplotlib, but requires
+`xlwt <http://pypi.python.org/pypi/xlwt>`_
+
+
+.. _toolkit_natgrid:
+
+Natgrid
+=======
+(*Not distributed with matplotlib*)
+
+mpl_toolkits.natgrid is an interface to natgrid C library for gridding
+irregularly spaced data.  This requires a separate installation of the
+natgrid toolkit from the sourceforge `download
+<http://sourceforge.net/project/showfiles.php?group_id=80706&package_id=142792>`_
+page.
+
 
 .. _hl_plotting:
 
-###################
 High-Level Plotting
-###################
+*******************
 
 Several projects have started to provide a higher-level interface to
 matplotlib.  These are independent projects.
@@ -152,3 +167,14 @@ ggplot
 
 `ggplot <https://github.com/yhat/ggplot>`_ is a port of the R ggplot2
 to python based on matplotlib.
+
+
+.. _toolkit_prettyplotlib:
+
+prettyplotlib
+=============
+(*Not distributed with matplotlib*)
+
+`prettyplotlib <https://olgabot.github.io/prettyplotlib>`_ is an extension
+to matplotlib which changes many of the defaults to make plots some
+consider more attractive.