Merge pull request #16372 from anntzer/griddoc

timhoffm · web-flow · commit 7a2971b1c236 · 2020-02-01T22:54:48.000+01:00
Dedupe ImageGrid doc from tutorial and docstring.
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
