resurrect axes_grid1 doc

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit d2758fd719cc · 2018-04-21T00:18:08.000+02:00
diff --git a/doc/_templates/autosummary.rst b/doc/_templates/autosummary.rst
@@ -6,11 +6,14 @@
 .. auto{{ objtype }}:: {{ objname }}
 
 {% if objtype in ['class', 'method', 'function'] %}
+{% if objname not in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
+                      'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
 
 .. include:: {{module}}.{{objname}}.examples
 
 .. raw:: html
 
     <div class="clearer"></div>
 
+{% endif %}
 {% endif %}
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
@@ -10,7 +10,7 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=.
 set BUILDDIR=build
 set SPHINXPROJ=matplotlib
-set SPHINXOPTS=-W
+set SPHINXOPTS=
 set O=
 
 %SPHINXBUILD% >NUL 2>NUL
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,4 @@
-'''
+"""
 Colorbar toolkit with two classes and a function:
 
     :class:`ColorbarBase`
@@ -16,8 +16,8 @@
 The :meth:`~matplotlib.figure.Figure.colorbar` method uses :func:`make_axes`
 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)
 
@@ -132,9 +132,9 @@
 Additional keyword arguments are of two kinds:
 
   axes properties:
-%s
+    %s
   colorbar properties:
-%s
+    %s
 
 If *mappable* is a :class:`~matplotlib.contours.ContourSet`, its *extend*
 kwarg is included automatically.
@@ -175,7 +175,7 @@
 unconventional value is to prevent underflow when log scale is used.
 ''' % (make_axes_kw_doc, colormap_kw_doc)
 
-docstring.interpd.update(colorbar_doc=colorbar_doc)
+#docstring.interpd.update(colorbar_doc=colorbar_doc)
 
 
 class CbarAxesLocator(object):
@@ -759,7 +759,9 @@ def update_bruteforce(self, mappable):
 def make_axes(parent, **kw):
     '''
     Resize and reposition a parent axes, and return a child
-    axes suitable for a colorbar::
+    axes suitable for a colorbar
+
+    ::
 
         cax, kw = make_axes(parent, **kw)
 
@@ -801,13 +803,14 @@ def make_axes(parent, **kw):
     cax.set_aspect(aspect, anchor=anchor, adjustable='box')
     return cax, kw
 
-
+@docstring.Substitution(colorbar_doc)
 def colorbar(mappable, cax=None, ax=None, **kw):
     """
     Create a colorbar for a ScalarMappable instance.
 
     Documentation for the pylab thin wrapper:
-    %(colorbar_doc)s
+
+    %s
     """
     import matplotlib.pyplot as plt
     if ax is None:
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
diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
