resurrect axes_grid1 doc

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit 68ade7863202 · 2018-04-18T18:10:06.000+02:00
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)``.
 
@@ -848,7 +848,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
@@ -1281,8 +1281,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/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst
@@ -10,7 +10,7 @@ The Matplotlib axes_grid Toolkit API
 .. currentmodule:: mpl_toolkits
 
 Axes Grid
----------
+=========
 .. note::
    
    There is an older version of the AxesGrid toolkit, ``axes_grid`` (instead of
@@ -20,9 +20,8 @@ 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
 
-   axes_grid1
-   axisartist
+
+:ref:`toolkit_axisartist-index`
+
+:ref:`toolkit_axesgrid1-index`
diff --git a/doc/api/toolkits/axes_grid1.rst b/doc/api/toolkits/axes_grid1.rst
@@ -22,3 +22,27 @@ See :ref:`axes_grid1_users-guide-index` for a guide on the usage of axes_grid1.
    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.
+
+
+.. currentmodule:: mpl_toolkits
+
+.. _toolkit-axes-grid1-api:
+
+:mod:`mpl_toolkits.axes_grid1`
+===================================
+
+.. 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
@@ -11,3 +11,29 @@ mpl's Axis class. This change was strongly motivated to support curvilinear grid
 
 You can find a tutorial describing usage of axisartist at
 :ref:`axisartist_users-guide-index`.
+
+
+.. currentmodule:: mpl_toolkits
+
+.. _toolkit-axisartist-api:
+
+:mod:`mpl_toolkits.axisartist`
+===================================
+
+.. 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/api/toolkits/index.rst b/doc/api/toolkits/index.rst
@@ -24,8 +24,8 @@ lighter weight solution for some use cases. Check out the
 :ref:`mplot3d tutorial <sphx_glr_tutorials_toolkits_mplot3d.py>` 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
 
@@ -54,7 +54,7 @@ collection of helper classes for displaying multiple axes in Matplotlib.
 .. toctree::
     :maxdepth: 2
 
-    axes_grid1/index.rst
+    axes_grid1.rst
 
 
 .. _toolkit_axisartist:
@@ -68,7 +68,7 @@ a custom Axes class that is meant to support curvilinear grids.
 .. toctree::
     :maxdepth: 2
 
-    axisartist/index.rst
+    axisartist.rst
 
 
 API
diff --git a/doc/api/toolkits/mplot3d/faq.rst b/doc/api/toolkits/mplot3d/faq.rst
diff --git a/doc/api/toolkits/mplot3d/index.rst b/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 :ref:`mplot3d tutorial <sphx_glr_tutorials_toolkits_mplot3d.py>` 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/make.bat b/doc/make.bat
@@ -35,4 +35,4 @@ goto end
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
-popd
+popd
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -58,8 +58,9 @@ def _stale_figure_callback(self, val):
 
 class AxesStack(Stack):
     """
-    Specialization of the `.Stack` to handle all tracking of `.Axes` in a
-    `.Figure`. This stack stores ``key, (ind, axes)`` pairs, where:
+    Specialization of the `.Stack` to handle all tracking of
+    `~matplotlib.axes.Axes` in a `.Figure`.
+    This stack stores ``key, (ind, axes)`` pairs, where:
 
         * **key** should be a hash of the args and kwargs
           used in generating the Axes.
@@ -994,7 +995,8 @@ def set_frameon(self, b):
 
     def delaxes(self, ax):
         """
-        Remove the `.Axes` *ax* from the figure and update the current axes.
+        Remove the `~matplotlib.axes.Axes` *ax* from the figure and update the
+        current axes.
         """
         self._axstack.remove(ax)
         for func in self._axobservers:
@@ -2114,7 +2116,8 @@ def align_xlabels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list of (or ndarray) `.Axes` to align the xlabels.
+            Optional list of (or ndarray) `~matplotlib.axes.Axes`
+            to align the xlabels.
             Default is to align all axes on the figure.
 
         See Also
@@ -2182,7 +2185,8 @@ def align_ylabels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list (or ndarray) of `.Axes` to align the ylabels.
+            Optional list (or ndarray) of `~matplotlib.axes.Axes`
+            to align the ylabels.
             Default is to align all axes on the figure.
 
         See Also
@@ -2245,7 +2249,8 @@ def align_labels(self, axs=None):
         Parameters
         ----------
         axs : list of `~matplotlib.axes.Axes`
-            Optional list (or ndarray) of `.Axes` to align the labels.
+            Optional list (or ndarray) of `~matplotlib.axes.Axes`
+            to align the labels.
             Default is to align all axes on the figure.
 
         See Also
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -346,7 +346,7 @@ def __init__(self, parent, handles, labels,
         """
         Parameters
         ----------
-        parent : `.Axes` or `.Figure`
+        parent : `~matplotlib.axes.Axes` or `.Figure`
             The artist that contains the legend.
 
         handles : sequence of `.Artist`
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -782,9 +782,9 @@ def axes(arg=None, **kwargs):
         - 4-tuple of floats *rect* = ``[left, bottom, width, height]``.
           A new axes is added with dimensions *rect* in normalized
           (0, 1) units using `~.Figure.add_axes` on the current figure.
-        - `.Axes`: This is equivalent to `.pyplot.sca`. It sets the current
-          axes to *arg*. Note: This implicitly changes the current figure to
-          the parent of *arg*.
+        - `~matplotlib.axes.Axes`: This is equivalent to `.pyplot.sca`.
+          It sets the current axes to *arg*. Note: This implicitly
+          changes the current figure to the parent of *arg*.
 
           .. note:: The use of an Axes as an argument is deprecated and will be
                     removed in v3.0. Please use `.pyplot.sca` instead.
@@ -898,16 +898,16 @@ def subplot(*args, **kwargs):
 
        subplot(nrows, ncols, index, **kwargs)
 
-    In the current figure, create and return an `.Axes`, at position *index*
-    of a (virtual) grid of *nrows* by *ncols* axes.  Indexes go from 1 to
-    ``nrows * ncols``, incrementing in row-major order.
+    In the current figure, create and return an `~matplotlib.axes.Axes`,
+    at position *index* of a (virtual) grid of *nrows* by *ncols* axes.
+    Indexes go from 1 to ``nrows * ncols``, incrementing in row-major order.
 
     If *nrows*, *ncols* and *index* are all less than 10, they can also be
     given as a single, concatenated, three-digit number.
 
     For example, ``subplot(2, 3, 3)`` and ``subplot(233)`` both create an
-    `.Axes` at the top right corner of the current figure, occupying half of
-    the figure height and a third of the figure width.
+    `matplotlib.axes.Axes` at the top right corner of the current figure,
+    occupying half of the figure height and a third of the figure width.
 
     .. note::
 
diff --git a/lib/mpl_toolkits/axes_grid1/colorbar.py b/lib/mpl_toolkits/axes_grid1/colorbar.py
@@ -1,4 +1,8 @@
-'''
+"""
+================
+Colorbar toolkit
+================
+
 Colorbar toolkit with two classes and a function:
 
     :class:`ColorbarBase`
@@ -17,7 +21,8 @@
 and :class:`Colorbar`; the :func:`~matplotlib.pyplot.colorbar` function
 is a thin wrapper over :meth:`~matplotlib.figure.Figure.colorbar`.
 
-'''
+"""
+
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 
diff --git a/lib/mpl_toolkits/axisartist/axis_artist.py b/lib/mpl_toolkits/axisartist/axis_artist.py
@@ -59,7 +59,7 @@
 The text angles are actually relative to (90 + angle of the direction
 to the ticklabel), which gives 0 for bottom axis.
 
-                        left bottom right top
+ Parameter              left bottom right top
  ticklabels location    left right  right left
  axislabel location     left right  right left
  ticklabels angle       90    0      -90  180
@@ -83,6 +83,7 @@
  * AxisLabel : pad
 
 """
+
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 
diff --git a/lib/mpl_toolkits/axisartist/floating_axes.py b/lib/mpl_toolkits/axisartist/floating_axes.py
@@ -236,7 +236,7 @@ def __init__(self, aux_trans, extremes,
         objects which defines the transform and its inverse. The callables
         need take two arguments of array of source coordinates and
         should return two target coordinates:
-          e.g., x2, y2 = trans(x1, y1)
+        e.g., *x2, y2 = trans(x1, y1)*
         """
 
         self._old_values = None
diff --git a/tutorials/advanced/transforms_tutorial.py b/tutorials/advanced/transforms_tutorial.py
@@ -25,9 +25,9 @@
 |           |                             |controlled by xlim and ylim.       |
 +-----------+-----------------------------+-----------------------------------+
 |"axes"     |``ax.transAxes``             |The coordinate system of the       |
-|           |                             |`.Axes`; (0, 0) is bottom left of  |
-|           |                             |the axes, and (1, 1) is top right  |
-|           |                             |of the axes.                       |
+|           |                             |`~matplotlib.axes.Axes`; (0, 0)    |
+|           |                             |is bottom left of the axes, and    |
+|           |                             |(1, 1) is top right of the axes.   |
 +-----------+-----------------------------+-----------------------------------+
 |"figure"   |``fig.transFigure``          |The coordinate system of the       |
 |           |                             |`.Figure`; (0, 0) is bottom left   |
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -543,10 +543,11 @@ def docomplicated(suptitle=None):
 # Each item has a layoutbox associated with it. The nesting of gridspecs
 # created with `.GridSpecFromSubplotSpec` can be arbitrarily deep.
 #
-# Each `.Axes` has *two* layoutboxes.  The first one ``ax._layoutbox``
-# represents the outside of the Axes and all its decorations (i.e. ticklabels,
-# axis labels, etc.).  The second layoutbox corresponds to the Axes'
-# `ax.position`, which sets where in the figure the spines are placed.
+# Each ``~matplotlib.axes.Axes` has *two* layoutboxes.  The first one,
+# ``ax._layoutbox`` represents the outside of the Axes and all its
+# decorations (i.e. ticklabels,axis labels, etc.).
+# The second layoutbox corresponds to the Axes' `ax.position`, which sets
+# where in the figure the spines are placed.
 #
 # Why so many stacked containers?  Ideally, all that would be needed are the
 # Axes layout boxes. For the Gridspec case, a container is
@@ -625,10 +626,11 @@ def docomplicated(suptitle=None):
 # constraint on their widths because their subplotspecs occupy the same
 # number of columns (one in this example).
 #
-# The colorbar layout logic is contained in `~.colorbar.make_axes` which
-# call `._constrained_layout.layoutcolorbarsingle` for cbars attached to
-# a single axes, and `._constrained_layout.layoutcolorbargridspec` if the
-# colorbar is associated wiht a gridspec.
+# The colorbar layout logic is contained in `~matplotlib.colorbar.make_axes`
+# which calls `._constrained_layout.layoutcolorbarsingle`
+# for cbars attached to a single axes, and
+# `._constrained_layout.layoutcolorbargridspec` if the colorbar is associated
+# with a gridspec.
 
 fig, ax = plt.subplots(1, 2, constrained_layout=True)
 im = ax[0].pcolormesh(arr, **pc_kwargs)
diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
@@ -38,17 +38,20 @@
 `.pyplot` API       OO API              description
 =================== =================== ======================================
 `~.pyplot.text`     `~.Axes.text`       Add text at an arbitrary location of
-                                        the `.Axes`.
+                                        the `~matplotlib.axes.Axes`.
 
 `~.pyplot.annotate` `~.Axes.annotate`   Add an annotation, with an optional
                                         arrow, at an arbitrary location of the
-                                        `.Axes`.
+                                        `~matplotlib.axes.Axes`.
 
-`~.pyplot.xlabel`   `~.Axes.set_xlabel` Add a label to the `.Axes`\\'s x-axis.
+`~.pyplot.xlabel`   `~.Axes.set_xlabel` Add a label to the
+                                        `~matplotlib.axes.Axes`\\'s x-axis.
 
-`~.pyplot.ylabel`   `~.Axes.set_ylabel` Add a label to the `.Axes`\\'s y-axis.
+`~.pyplot.ylabel`   `~.Axes.set_ylabel` Add a label to the
+                                        `~matplotlib.axes.Axes`\\'s y-axis.
 
-`~.pyplot.title`    `~.Axes.set_title`  Add a title to the `.Axes`.
+`~.pyplot.title`    `~.Axes.set_title`  Add a title to the
+                                        `~matplotlib.axes.Axes`.
 
 `~.pyplot.figtext`  `~.Figure.text`     Add text at an arbitrary location of
                                         the `.Figure`.

-Original file line number
+Diff line change
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 :end
 -popd
 +popd