Dedupe ImageGrid doc from tutorial and docstring.

anntzer · anntzer · commit c32825082501 · 2020-01-30T11:33:48.000+01:00
ImageGrid is so little-maintained that I don't think we should have
duplicate argument lists in the tutorial and the docstring, given that
they *will* go out of sync (for more commonly used APIs, sure, we can
maintain the duplication, but here it's not worth it).  Add to the
docstring the relevant parts of the tutorial, and make the tutorial
point to the API docs.
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -23,6 +23,10 @@
     "button": [
       "doc/users/prev_whats_new/whats_new_3.1.0.rst:338"
     ],
+    "cbar_axes": [
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:48",
+      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:48"
+    ],
     "dividers": [
       "lib/mpl_toolkits/axes_grid1/colorbar.py:docstring of mpl_toolkits.axes_grid1.colorbar.ColorbarBase:29"
     ],
@@ -792,8 +796,8 @@
       "doc/api/prev_api_changes/api_changes_1.5.0.rst:44"
     ],
     "Size.from_any": [
-      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:73",
-      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:48"
+      "lib/mpl_toolkits/axes_grid1/axes_grid.py:docstring of mpl_toolkits.axes_grid1.axes_grid.ImageGrid:60",
+      "lib/mpl_toolkits/axisartist/axes_grid.py:docstring of mpl_toolkits.axisartist.axes_grid.ImageGrid:60"
     ],
     "Style": [
       "doc/devel/MEP/MEP26.rst:68"
@@ -892,13 +896,13 @@
       "doc/api/prev_api_changes/api_changes_3.1.0.rst:933"
     ],
     "axes_grid1": [
-      "doc/index.rst:184"
+      "doc/index.rst:154"
     ],
     "axis.Axis.get_ticks_position": [
       "doc/api/prev_api_changes/api_changes_3.1.0.rst:821"
     ],
     "axisartist": [
-      "doc/index.rst:184"
+      "doc/index.rst:154"
     ],
     "backend_bases.RendererBase": [
       "lib/matplotlib/backends/backend_template.py:docstring of matplotlib.backends.backend_template.RendererTemplate:4"
@@ -1506,7 +1510,7 @@
       "lib/mpl_toolkits/axisartist/axis_artist.py:docstring of mpl_toolkits.axisartist.axis_artist:26"
     ],
     "mplot3d": [
-      "doc/index.rst:184"
+      "doc/index.rst:154"
     ],
     "new_figure_manager": [
       "doc/devel/MEP/MEP23.rst:75"
@@ -1689,4 +1693,4 @@
       "lib/mpl_toolkits/mplot3d/axes3d.py:docstring of mpl_toolkits.mplot3d.axes3d.Axes3D.get_ylim3d:24"
     ]
   }
-}
+}
diff --git a/lib/mpl_toolkits/axes_grid1/axes_grid.py b/lib/mpl_toolkits/axes_grid1/axes_grid.py
@@ -82,12 +82,13 @@ def cla(self):
 
 class Grid:
     """
-    A class that creates a grid of Axes. In matplotlib, the axes
-    location (and size) is specified in the normalized figure
-    coordinates. This may not be ideal for images that needs to be
-    displayed with a given aspect ratio.  For example, displaying
-    images of a same size with some fixed padding between them cannot
-    be easily done in matplotlib. AxesGrid is used in such case.
+    A grid of Axes.
+
+    In Matplotlib, the axes location (and size) is specified in normalized
+    figure coordinates. This may not be ideal for images that needs to be
+    displayed with a given aspect ratio; for example, it is difficult to
+    display multiple images of a same size with some fixed padding between
+    them.  AxesGrid can be used in such case.
     """
 
     _defaultAxesClass = Axes
@@ -115,14 +116,25 @@ def __init__(self, fig,
         rect : (float, float, float, float) or int
             The axes position, as a ``(left, bottom, width, height)`` tuple or
             as a three-digit subplot position code (e.g., "121").
+        nrows_ncols : (int, int)
+            Number of rows and columns in the grid.
+        ngrids : int or None, default: None
+            If not None, only the first *ngrids* axes in the grid are created.
         direction : {"row", "column"}, default: "row"
+            Whether axes are created in row-major ("row by row") or
+            column-major order ("column by column").
         axes_pad : float or (float, float), default: 0.02
             Padding or (horizontal padding, vertical padding) between axes, in
             inches.
         add_all : bool, default: True
+            Whether to add the axes to the figure using `.Figure.add_axes`.
         share_all : bool, default: False
+            Whether all axes share their x- and y-axis.  Overrides *share_x*
+            and *share_y*.
         share_x : bool, default: True
+            Whether all axes of a column share their x-axis.
         share_y : bool, default: True
+            Whether all axes of a row share their y-axis.
         label_mode : {"L", "1", "all"}, default: "L"
             Determines which axes will get tick labels:
 
@@ -133,6 +145,8 @@ def __init__(self, fig,
 
         axes_class : subclass of `matplotlib.axes.Axes`, default: None
         aspect : bool, default: False
+            Whether the axes aspect ratio follows the aspect ratio of the data
+            limits.
         """
         self._nrows, self._ncols = nrows_ncols
 
@@ -332,14 +346,7 @@ def get_vsize_hsize(self):
 
 
 class ImageGrid(Grid):
-    """
-    A class that creates a grid of Axes. In matplotlib, the axes
-    location (and size) is specified in the normalized figure
-    coordinates. This may not be ideal for images that needs to be
-    displayed with a given aspect ratio.  For example, displaying
-    images of a same size with some fixed padding between them cannot
-    be easily done in matplotlib. ImageGrid is used in such case.
-    """
+    # docstring inherited
 
     _defaultCbarAxesClass = CbarAxes
 
@@ -368,13 +375,24 @@ def __init__(self, fig,
         rect : (float, float, float, float) or int
             The axes position, as a ``(left, bottom, width, height)`` tuple or
             as a three-digit subplot position code (e.g., "121").
+        nrows_ncols : (int, int)
+            Number of rows and columns in the grid.
+        ngrids : int or None, default: None
+            If not None, only the first *ngrids* axes in the grid are created.
         direction : {"row", "column"}, default: "row"
-        axes_pad : float or (float, float), default: 0.02
+            Whether axes are created in row-major ("row by row") or
+            column-major order ("column by column").  This also affects the
+            order in which axes are accessed using indexing (``grid[index]``).
+        axes_pad : float or (float, float), default: 0.02in
             Padding or (horizontal padding, vertical padding) between axes, in
             inches.
         add_all : bool, default: True
+            Whether to add the axes to the figure using `.Figure.add_axes`.
         share_all : bool, default: False
+            Whether all axes share their x- and y-axis.
         aspect : bool, default: True
+            Whether the axes aspect ratio follows the aspect ratio of the data
+            limits.
         label_mode : {"L", "1", "all"}, default: "L"
             Determines which axes will get tick labels:
 
@@ -383,10 +401,16 @@ def __init__(self, fig,
             - "1": Only the bottom left axes is labelled.
             - "all": all axes are labelled.
 
-        cbar_mode : {"each", "single", "edge", None }, default: None
+        cbar_mode : {"each", "single", "edge", None}, default: None
+            Whether to create a colorbar for "each" axes, a "single" colorbar
+            for the entire grid, colorbars only for axes on the "edge"
+            determined by *cbar_location*, or no colorbars.  The colorbars are
+            stored in the :attr:`cbar_axes` attribute.
         cbar_location : {"left", "right", "bottom", "top"}, default: "right"
         cbar_pad : float, default: None
+            Padding between the image axes and the colorbar axes.
         cbar_size : size specification (see `.Size.from_any`), default: "5%"
+            Colorbar size.
         cbar_set_cax : bool, default: True
             If True, each axes in the grid has a *cax* attribute that is bound
             to associated *cbar_axes*.
diff --git a/tutorials/toolkits/axes_grid.py b/tutorials/toolkits/axes_grid.py
@@ -40,12 +40,14 @@
 ImageGrid
 ---------
 
-A class that creates a grid of Axes. In matplotlib, the axes location
-(and size) is specified in the normalized figure coordinates. This may
-not be ideal for images that needs to be displayed with a given aspect
-ratio.  For example, displaying images of a same size with some fixed
-padding between them cannot be easily done in matplotlib. ImageGrid is
-used in such case.
+A grid of Axes.
+
+In Matplotlib, the axes location (and size) is specified in normalized
+figure coordinates. This may not be ideal for images that needs to be
+displayed with a given aspect ratio; for example, it is difficult to
+display multiple images of a same size with some fixed padding between
+them.  `~.axes_grid1.axes_grid.ImageGrid` can be used in such a case; see its
+docs for a detailed list of the parameters it accepts.
 
 .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png
    :target: ../../gallery/axes_grid1/simple_axesgrid.html
@@ -78,76 +80,6 @@
   your mouse in interactive backends) of one axes will affect all
   other shared axes.
 
-When initialized, ImageGrid creates given number (*ngrids* or *ncols* *
-*nrows* if *ngrids* is None) of Axes instances. A sequence-like
-interface is provided to access the individual Axes instances (e.g.,
-grid[0] is the first Axes in the grid. See below for the order of
-axes).
-
-ImageGrid takes following arguments,
-
- ============= ========   ================================================
- Name          Default    Description
- ============= ========   ================================================
- fig
- rect
- nrows_ncols              number of rows and cols. e.g., (2, 2)
- ngrids        None       number of grids. nrows x ncols if None
- direction     "row"      increasing direction of axes number. [row|column]
- axes_pad      0.02       pad between axes in inches
- add_all       True       Add axes to figures if True
- share_all     False      xaxis & yaxis of all axes are shared if True
- aspect        True       aspect of axes
- label_mode    "L"        location of tick labels thaw will be displayed.
-                          "1" (only the lower left axes),
-                          "L" (left most and bottom most axes),
-                          or "all".
- cbar_mode     None       [None|single|each]
- cbar_location "right"    [right|top]
- cbar_pad      None       pad between image axes and colorbar axes
- cbar_size     "5%"       size of the colorbar
- axes_class    None
- ============= ========   ================================================
-
- *rect*
-  specifies the location of the grid. You can either specify
-  coordinates of the rectangle to be used (e.g., (0.1, 0.1, 0.8, 0.8)
-  as in the Axes), or the subplot-like position (e.g., "121").
-
- *direction*
-  means the increasing direction of the axes number.
-
- *aspect*
-  By default (False), widths and heights of axes in the grid are
-  scaled independently. If True, they are scaled according to their
-  data limits (similar to aspect parameter in Matplotlib).
-
- *share_all*
-  if True, xaxis and yaxis of all axes are shared.
-
- *direction*
-  direction of increasing axes number.  For "row",
-
-   +---------+---------+
-   | grid[0] | grid[1] |
-   +---------+---------+
-   | grid[2] | grid[3] |
-   +---------+---------+
-
-  For "column",
-
-   +---------+---------+
-   | grid[0] | grid[2] |
-   +---------+---------+
-   | grid[1] | grid[3] |
-   +---------+---------+
-
-You can also create a colorbar (or colorbars). You can have colorbar
-for each axes (cbar_mode="each"), or you can have a single colorbar
-for the grid (cbar_mode="single"). The colorbar can be placed on your
-right, or top. The axes for each colorbar is stored as a *cbar_axes*
-attribute.
-
 The examples below show what you can do with ImageGrid.
 
 .. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png
