Improve docs on gridspec

timhoffm · timhoffm · commit eabe58baa57f · 2019-06-05T22:55:52.000+02:00
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -1,16 +1,12 @@
-"""
-:mod:`~matplotlib.gridspec` is a module which specifies the location
-of the subplot in the figure.
-
-    `GridSpec`
-        specifies the geometry of the grid that a subplot will be
-        placed. The number of rows and number of columns of the grid
-        need to be set. Optionally, the subplot layout parameters
-        (e.g., left, right, etc.) can be tuned.
+r"""
+:mod:`~matplotlib.gridspec` contains classes that help to layout multiple
+`~axes.Axes` in a grid-like pattern within a figure.
 
-    `SubplotSpec`
-        specifies the location of the subplot in the given `GridSpec`.
+The `GridSpec` specifies the overall grid structure. Individual cells within
+the grid are referenced by `SubplotSpec`\s.
 
+See the tutorial :ref:`sphx_glr_tutorials_intermediate_gridspec.py` for a
+comprehensive usage guide.
 """
 
 import copy
@@ -55,16 +51,16 @@ def __repr__(self):
             )
 
     def get_geometry(self):
-        'get the geometry of the grid, e.g., 2,3'
+        """
+        Return a tuple containing the number of rows and columns in the grid.
+        """
         return self._nrows, self._ncols
 
     def get_subplot_params(self, figure=None, fig=None):
         pass
 
     def new_subplotspec(self, loc, rowspan=1, colspan=1):
-        """
-        Create and return a SubplotSpec instance.
-        """
+        """Create and return a `.SubplotSpec` instance."""
         loc1, loc2 = loc
         subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
         return subplotspec
@@ -89,7 +85,7 @@ def get_height_ratios(self):
 
     def get_grid_positions(self, fig, raw=False):
         """
-        return lists of bottom and top position of rows, left and
+        Return lists of bottom and top position of rows, left and
         right positions of columns.
 
         If raw=True, then these are all in units relative to the container
@@ -142,8 +138,7 @@ def get_grid_positions(self, fig, raw=False):
         return fig_bottoms, fig_tops, fig_lefts, fig_rights
 
     def __getitem__(self, key):
-        """Create and return a SubplotSpec instance.
-        """
+        """Create and return a `.SubplotSpec` instance."""
         nrows, ncols = self.get_geometry()
 
         def _normalize(key, size, axis):  # Includes last index.
@@ -182,11 +177,10 @@ def _normalize(key, size, axis):  # Includes last index.
 
 class GridSpec(GridSpecBase):
     """
-    A class that specifies the geometry of the grid that a subplot
-    will be placed. The location of grid is determined by similar way
-    as the SubplotParams.
-    """
+    Specifies the geometry of the grid that a subplot can be placed in.
 
+    The location of grid is determined by similar way as the SubplotParams.
+    """
     def __init__(self, nrows, ncols, figure=None,
                  left=None, bottom=None, right=None, top=None,
                  wspace=None, hspace=None,
@@ -328,7 +322,7 @@ def tight_layout(self, figure, renderer=None,
             fraction of the font-size.
         h_pad, w_pad : float, optional
             Padding (height/width) between edges of adjacent subplots.
-            Defaults to ``pad_inches``.
+            Defaults to *pad*.
         rect : tuple of 4 floats, optional
             (left, bottom, right, top) rectangle in normalized figure
             coordinates that the whole subplots area (including labels) will
@@ -403,22 +397,33 @@ def get_subplot_params(self, figure=None):
                                         wspace=wspace, hspace=hspace)
 
     def get_topmost_subplotspec(self):
-        """Get the topmost SubplotSpec instance associated with the subplot."""
+        """
+        Return the topmost `.SubplotSpec` instance associated with the subplot.
+        """
         return self._subplot_spec.get_topmost_subplotspec()
 
 
 class SubplotSpec:
-    """Specifies the location of the subplot in the given `GridSpec`.
     """
+    Specifies the location of a subplot in a `GridSpec`.
 
-    def __init__(self, gridspec, num1, num2=None):
-        """
+    .. note::
+
+        Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you
+        will typically obtain one from a `GridSpec` using item-access.
+
+    Parameters
+    ----------
+    gridspec : `~matplotlib.gridspec.GridSpec`
+        The GridSpec, which the subplot is referencing.
+    num1, num2 : int
         The subplot will occupy the num1-th cell of the given
         gridspec.  If num2 is provided, the subplot will span between
         num1-th cell and num2-th cell *inclusive*.
 
         The index starts from 0.
-        """
+    """
+    def __init__(self, gridspec, num1, num2=None):
         self._gridspec = gridspec
         self.num1 = num1
         self.num2 = num2
@@ -464,18 +469,19 @@ def get_gridspec(self):
 
     def get_geometry(self):
         """
-        Get the subplot geometry (``n_rows, n_cols, start, stop``).
+        Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``.
 
-        start and stop are the index of the start and stop of the
-        subplot.
+        The indices *start* and *stop* define the range of the subplot within
+        the `GridSpec`. *stop* is inclusive (i.e. for a single cell
+        ``start == stop``).
         """
         rows, cols = self.get_gridspec().get_geometry()
         return rows, cols, self.num1, self.num2
 
     def get_rows_columns(self):
         """
-        Get the subplot row and column numbers:
-        (``n_rows, n_cols, row_start, row_stop, col_start, col_stop``)
+        Return the subplot row and column numbers as a tuple
+        ``(n_rows, n_cols, row_start, row_stop, col_start, col_stop)``.
         """
         gridspec = self.get_gridspec()
         nrows, ncols = gridspec.get_geometry()
@@ -484,7 +490,8 @@ def get_rows_columns(self):
         return nrows, ncols, row_start, row_stop, col_start, col_stop
 
     def get_position(self, figure, return_all=False):
-        """Update the subplot position from ``figure.subplotpars``.
+        """
+        Update the subplot position from ``figure.subplotpars``.
         """
         gridspec = self.get_gridspec()
         nrows, ncols = gridspec.get_geometry()
@@ -504,14 +511,20 @@ def get_position(self, figure, return_all=False):
             return figbox
 
     def get_topmost_subplotspec(self):
-        'get the topmost SubplotSpec instance associated with the subplot'
+        """
+        Return the topmost `SubplotSpec` instance associated with the subplot.
+        """
         gridspec = self.get_gridspec()
         if hasattr(gridspec, "get_topmost_subplotspec"):
             return gridspec.get_topmost_subplotspec()
         else:
             return self
 
     def __eq__(self, other):
+        """
+        Two SubplotSpecs are considered equal if they refer to the same
+        position(s) in the same `GridSpec`.
+        """
         # other may not even have the attributes we are checking.
         return ((self._gridspec, self.num1, self.num2)
                 == (getattr(other, "_gridspec", object()),
@@ -523,7 +536,9 @@ def __hash__(self):
 
     def subgridspec(self, nrows, ncols, **kwargs):
         """
-        Return a `.GridSpecFromSubplotSpec` that has this subplotspec as
+        Create a GridSpec within this subplot.
+
+        The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as
         a parent.
 
         Parameters
@@ -536,12 +551,12 @@ def subgridspec(self, nrows, ncols, **kwargs):
 
         Returns
         -------
-        gridspec : `.GridSpec`
+        gridspec : `.GridSpecFromSubplotSpec`
 
         Other Parameters
         ----------------
         **kwargs
-            All other parameters are passed to `.GridSpec`.
+            All other parameters are passed to `.GridSpecFromSubplotSpec`.
 
         See Also
         --------
@@ -559,5 +574,4 @@ def subgridspec(self, nrows, ncols, **kwargs):
             for i in range(3):
                 fig.add_subplot(gssub[0, i])
         """
-
         return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs)
diff --git a/lib/matplotlib/tight_layout.py b/lib/matplotlib/tight_layout.py
@@ -281,7 +281,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
         fraction of the font size.
     h_pad, w_pad : float
         Padding (height/width) between edges of adjacent subplots.  Defaults to
-        *pad_inches*.
+        *pad*.
     rect : Tuple[float, float, float, float], optional
         (left, bottom, right, top) rectangle in normalized figure coordinates
         that the whole subplots area (including labels) will fit into.
