Merge pull request #15024 from timhoffm/doc-gridspecbase

tacaswell · web-flow · commit 49cec86da53f · 2019-08-10T21:00:00.000-04:00
DOC: Update docs of GridSpecBase
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -30,9 +30,18 @@ class GridSpecBase:
 
     def __init__(self, nrows, ncols, height_ratios=None, width_ratios=None):
         """
-        The number of rows and number of columns of the grid need to
-        be set. Optionally, the ratio of heights and widths of rows and
-        columns can be specified.
+        Parameters
+        ----------
+        nrows, ncols : int
+            The number of rows and columns of the grid.
+        width_ratios : array-like of length *ncols*, optional
+            Defines the relative widths of the columns. Each column gets a
+            relative width of ``width_ratios[i] / sum(width_ratios)``.
+            If not given, all columns will have the same width.
+        height_ratios : array-like of length *nrows*, optional
+            Defines the relative heights of the rows. Each column gets a
+            relative height of ``height_ratios[i] / sum(height_ratios)``.
+            If not given, all rows will have the same height.
         """
         self._nrows, self._ncols = nrows, ncols
         self.set_height_ratios(height_ratios)
@@ -57,39 +66,85 @@ def get_geometry(self):
         return self._nrows, self._ncols
 
     def get_subplot_params(self, figure=None):
+        # Must be implemented in subclasses
         pass
 
     def new_subplotspec(self, loc, rowspan=1, colspan=1):
-        """Create and return a `.SubplotSpec` instance."""
+        """
+        Create and return a `.SubplotSpec` instance.
+
+        Parameters
+        ----------
+        loc : (int, int)
+            The position of the subplot in the grid as
+            ``(row_index, column_index)``.
+        rowspan, colspan : int, default: 1
+            The number of rows and columns the subplot should span in the grid.
+        """
         loc1, loc2 = loc
         subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
         return subplotspec
 
     def set_width_ratios(self, width_ratios):
+        """
+        Set the relative widths of the columns.
+
+        *width_ratios* must be of length *ncols*. Each column gets a relative
+        width of ``width_ratios[i] / sum(width_ratios)``.
+        """
         if width_ratios is not None and len(width_ratios) != self._ncols:
             raise ValueError('Expected the given number of width ratios to '
                              'match the number of columns of the grid')
         self._col_width_ratios = width_ratios
 
     def get_width_ratios(self):
+        """
+        Return the width ratios.
+
+        This is *None* if no width ratios have been set explicitly.
+        """
         return self._col_width_ratios
 
     def set_height_ratios(self, height_ratios):
+        """
+        Set the relative heights of the rows.
+
+        *height_ratios* must be of length *nrows*. Each row gets a relative
+        height of ``height_ratios[i] / sum(height_ratios)``.
+        """
         if height_ratios is not None and len(height_ratios) != self._nrows:
             raise ValueError('Expected the given number of height ratios to '
                              'match the number of rows of the grid')
         self._row_height_ratios = height_ratios
 
     def get_height_ratios(self):
+        """
+        Return the height ratios.
+
+        This is *None* if no height ratios have been set explicitly.
+        """
         return self._row_height_ratios
 
     def get_grid_positions(self, fig, raw=False):
         """
-        Return lists of bottom and top position of rows, left and
-        right positions of columns.
+        Return the positions of the grid cells in figure coordinates.
+
+        Parameters
+        ----------
+        fig : `~matplotlib.figure.Figure`
+            The figure the grid should be applied to. The subplot parameters
+            (margins and spacing between subplots) are taken from *fig*.
+        raw : bool, default: False
+            If *True*, the subplot parameters of the figure are not taken
+            into account. The grid spans the range [0, 1] in both directions
+            without margins and there is no space between grid cells. This is
+            used for constrained_layout.
 
-        If raw=True, then these are all in units relative to the container
-        with no margins.  (used for constrained_layout).
+        Returns
+        -------
+        bottoms, tops, lefts, rights : array
+            The bottom, top, left, right positions of the grid cells in
+            figure coordinates.
         """
         nrows, ncols = self.get_geometry()
 
@@ -192,11 +247,8 @@ def __init__(self, nrows, ncols, figure=None,
 
         Parameters
         ----------
-        nrows : int
-            Number of rows in grid.
-
-        ncols : int
-            Number or columns in grid.
+        nrows, ncols : int
+            The number of rows and columns of the grid.
 
         figure : `~.figure.Figure`, optional
 
@@ -213,11 +265,15 @@ def __init__(self, nrows, ncols, figure=None,
             The amount of height reserved for space between subplots,
             expressed as a fraction of the average axis height.
 
-        width_ratios : length *ncols* iterable, optional
-            Width ratios of the columns.
+        width_ratios : array-like of length *ncols*, optional
+            Defines the relative widths of the columns. Each column gets a
+            relative width of ``width_ratios[i] / sum(width_ratios)``.
+            If not given, all columns will have the same width.
 
-        height_ratios : length *nrows* iterable, optional
-            Height ratios of the rows.
+        height_ratios : array-like of length *nrows*, optional
+            Defines the relative heights of the rows. Each column gets a
+            relative height of ``height_ratios[i] / sum(height_ratios)``.
+            If not given, all rows will have the same height.
 
         Notes
         -----
