Merge pull request #16744 from anntzer/axes_grid-tut

timhoffm · web-flow · commit 78426fa7f427 · 2020-03-14T21:37:16.000+01:00
Reword axes_divider tutorial.
diff --git a/tutorials/toolkits/axes_grid.py b/tutorials/toolkits/axes_grid.py
@@ -328,74 +328,67 @@
   units that are used to determine the size of each axes. For example,
   you can specify a fixed size.
 
-* :class:`~mpl_toolkits.axes_grid1.axes_divider.Divider` is the class that
+* `~mpl_toolkits.axes_grid1.axes_divider.Divider` is the class that
   calculates the axes position. It divides the given rectangular area into
   several areas. The divider is initialized by setting the lists of horizontal
   and vertical sizes on which the division will be based. Then use
   :meth:`~mpl_toolkits.axes_grid1.axes_divider.Divider.new_locator`, which
   returns a callable object that can be used to set the axes_locator of the
   axes.
 
+Here, we demonstrate how to achieve the following layout: we want to position
+axes in a 3x4 grid (note that `.Divider` makes row indices start from the
+*bottom*\(!) of the grid):
 
-First, initialize the divider by specifying its grids, i.e.,
-horizontal and vertical::
+.. code-block:: none
 
-    rect = [0.2, 0.2, 0.6, 0.6]
-    horiz = [h0, h1, h2, h3]
-    vert = [v0, v1, v2]
-    divider = Divider(fig, rect, horiz, vert)
+   +--------+--------+--------+--------+
+   | (2, 0) | (2, 1) | (2, 2) | (2, 3) |
+   +--------+--------+--------+--------+
+   | (1, 0) | (1, 1) | (1, 2) | (1, 3) |
+   +--------+--------+--------+--------+
+   | (0, 0) | (0, 1) | (0, 2) | (0, 3) |
+   +--------+--------+--------+--------+
+
+such that the bottom row has a fixed height of 2 (inches) and the top two rows
+have a height ratio of 2 (middle) to 3 (top).  (For example, if the grid has
+a size of 7 inches, the bottom row will be 2 inches, the middle row also 2
+inches, and the top row 3 inches.)
 
-where rect is a bounds of the box that will be divided and h0, ..., h3,
-v0, ..., v2 need to be instance of classes in the
-:mod:`~mpl_toolkits.axes_grid1.axes_size`.  They have *get_size* method
-that returns a tuple of two floats. The first float is the relative
-size, and the second float is the absolute size. Consider a following
-grid.
+These constraints are specified using classes from the
+:mod:`~mpl_toolkits.axes_grid1.axes_size` module, namely::
 
-+------+-----+-----+-----+
-| v0   |     |     |     |
-+------+-----+-----+-----+
-| v1   |     |     |     |
-+------+-----+-----+-----+
-|h0, v2| h1  | h2  | h3  |
-+------+-----+-----+-----+
+    from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled
+    vert = [Fixed(2), Scaled(2), Scaled(3)]
 
+(More generally, :mod:`~mpl_toolkits.axes_grid1.axes_size` classes define a
+``get_size(renderer)`` method that returns a pair of floats -- a relative size,
+and an absolute size.  ``Fixed(2).get_size(renderer)`` returns ``(0, 2)``;
+``Scaled(2).get_size(renderer)`` returns ``(2, 0)``.)
 
-* v0 => 0, 2
-* v1 => 2, 0
-* v2 => 3, 0
+We use these constraints to initialize a `.Divider` object::
 
-The height of the bottom row is always 2 (axes_divider internally
-assumes that the unit is inches). The first and the second rows have a
-height ratio of 2:3. For example, if the total height of the grid is 6,
-then the first and second row will each occupy 2/(2+3) and 3/(2+3) of
-(6-1) inches. The widths of the horizontal columns will be similarly
-determined. When the aspect ratio is set, the total height (or width) will
-be adjusted accordingly.
+    rect = [0.2, 0.2, 0.6, 0.6]  # Position of the grid in the figure.
+    vert = [Fixed(2), Scaled(2), Scaled(3)]  # As above.
+    horiz = [...]  # Some other horizontal constraints.
+    divider = Divider(fig, rect, horiz, vert)
 
-The :mod:`mpl_toolkits.axes_grid1.axes_size` contains several classes
-that can be used to set the horizontal and vertical configurations. For
-example, for vertical configuration one could use::
+then use `.Divider.new_locator` to create an `.AxesLocator` instance for a
+given grid entry::
 
-  from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled
-  vert = [Fixed(2), Scaled(2), Scaled(3)]
+    locator = divider.new_locator(nx=0, ny=1)  # Grid entry (1, 0).
 
-After you set up the divider object, then you create a locator
-instance that will be given to the axes object.::
+and make it responsible for locating the axes::
 
-     locator = divider.new_locator(nx=0, ny=1)
-     ax.set_axes_locator(locator)
+    ax.set_axes_locator(locator)
 
-The return value of the new_locator method is an instance of the
-AxesLocator class. It is a callable object that returns the
-location and size of the cell at the first column and the second row.
-You may create a locator that spans over multiple cells.::
+The `.AxesLocator` is a callable object that returns the location and size of
+the cell at the first column and the second row.
 
-     locator = divider.new_locator(nx=0, nx=2, ny=1)
+Locators that spans over multiple cells can be created with, e.g.::
 
-The above locator, when called, will return the position and size of
-the cells spanning the first and second column and the first row. In
-this example, it will return [0:2, 1].
+    # Columns #0 and #1 ("0-2 range"), row #1.
+    locator = divider.new_locator(nx=0, nx1=2, ny=1)
 
 See the example,
 
@@ -404,15 +397,11 @@
    :align: center
    :scale: 50
 
-   Simple Axes Divider2
-
-You can adjust the size of each axes according to its x or y
+You can also adjust the size of each axes according to its x or y
 data limits (AxesX and AxesY).
 
 .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png
    :target: ../../gallery/axes_grid1/simple_axes_divider3.html
    :align: center
    :scale: 50
-
-   Simple Axes Divider3
 """
