Merge pull request #10666 from timhoffm/doc-figure-part-2

dstansby · timhoffm · commit 68beb9abf43e · 2018-03-18T01:31:03.000+01:00
More figure-related doc updates
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -62,8 +62,8 @@ def _stale_figure_callback(self, val):
 
 class AxesStack(Stack):
     """
-    Specialization of the Stack to handle all tracking of Axes in a Figure.
-    This stack stores ``key, (ind, axes)`` pairs, where:
+    Specialization of the `.Stack` to handle all tracking of `.Axes` in a
+    `.Figure`. This stack stores ``key, (ind, axes)`` pairs, where:
 
         * **key** should be a hash of the args and kwargs
           used in generating the Axes.
@@ -81,7 +81,7 @@ def __init__(self):
 
     def as_list(self):
         """
-        Return a list of the Axes instances that have been added to the figure
+        Return a list of the Axes instances that have been added to the figure.
         """
         ia_list = [a for k, a in self._elements]
         ia_list.sort()
@@ -90,7 +90,7 @@ def as_list(self):
     def get(self, key):
         """
         Return the Axes instance that was added with *key*.
-        If it is not present, return None.
+        If it is not present, return *None*.
         """
         item = dict(self._elements).get(key)
         if item is None:
@@ -692,31 +692,55 @@ def suptitle(self, t, **kwargs):
         """
         Add a centered title to the figure.
 
-        kwargs are :class:`matplotlib.text.Text` properties.  Using figure
-        coordinates, the defaults are:
+        Parameters
+        ----------
+        t : str
+            The title text.
+
+        x : float, default 0.5
+            The x location of the text in figure coordinates.
+
+        y : float, default 0.98
+            The y location of the text in figure coordinates.
+
+        horizontalalignment, ha : {'center', 'left', right'}, default: 'center'
+            The horizontal alignment of the text.
 
-          x : 0.5
-            The x location of the text in figure coords
+        verticalalignment, va : {'top', 'center', 'bottom', 'baseline'}, \
+default: 'top'
+            The vertical alignment of the text.
 
-          y : 0.98
-            The y location of the text in figure coords
+        fontsize, size : default: :rc:`figure.titlesize`
+            The font size of the text. See `.Text.set_size` for possible
+            values.
+
+        fontweight, weight : default: :rc:`figuretitleweight`
+            The font weight of the text. See `.Text.set_weight` for possible
+            values.
+
+
+        Returns
+        -------
+            text
+                The `.Text` instance of the title.
 
-          horizontalalignment : 'center'
-            The horizontal alignment of the text
 
-          verticalalignment : 'top'
-            The vertical alignment of the text
+        Other Parameters
+        ----------------
+        fontproperties : None or dict, optional
+            A dict of font properties. If *fontproperties* is given the
+            default values for font size and weight are taken from the
+            `FontProperties` defaults. :rc:`figure.titlesize` and
+            :rc:`figure.titleweight` are ignored in this case.
 
-        If the `fontproperties` keyword argument is given then the
-        rcParams defaults for `fontsize` (`figure.titlesize`) and
-        `fontweight` (`figure.titleweight`) will be ignored in favour
-        of the `FontProperties` defaults.
+        **kwargs
+            Additional kwargs are :class:`matplotlib.text.Text` properties.
 
-        A :class:`matplotlib.text.Text` instance is returned.
 
-        Example::
+        Examples
+        --------
 
-          fig.suptitle('this is the figure title', fontsize=12)
+        >>> fig.suptitle('This is the figure title', fontsize=12)
         """
         x = kwargs.pop('x', 0.5)
         y = kwargs.pop('y', 0.98)
@@ -871,9 +895,9 @@ def figimage(self, X,
         return im
 
     def set_size_inches(self, w, h=None, forward=True):
-        """Set the figure size in inches (1in == 2.54cm)
+        """Set the figure size in inches.
 
-        Usage ::
+        Call signatures::
 
              fig.set_size_inches(w, h)  # OR
              fig.set_size_inches((w, h))
@@ -882,7 +906,7 @@ def set_size_inches(self, w, h=None, forward=True):
         automatically updated; e.g., you can resize the figure window
         from the shell
 
-        ACCEPTS: a w, h tuple with w, h in inches
+        ACCEPTS: a (w, h) tuple with w, h in inches
 
         See Also
         --------
@@ -968,9 +992,9 @@ def set_facecolor(self, color):
 
     def set_dpi(self, val):
         """
-        Set the dots-per-inch of the figure
+        Set the resolution of the figure in dots-per-inch.
 
-        ACCEPTS: float
+        .. ACCEPTS: float
         """
         self.dpi = val
         self.stale = True
@@ -979,21 +1003,21 @@ def set_figwidth(self, val, forward=True):
         """
         Set the width of the figure in inches
 
-        ACCEPTS: float
+        .. ACCEPTS: float
         """
         self.set_size_inches(val, self.get_figheight(), forward=forward)
 
     def set_figheight(self, val, forward=True):
         """
         Set the height of the figure in inches
 
-        ACCEPTS: float
+        .. ACCEPTS: float
         """
         self.set_size_inches(self.get_figwidth(), val, forward=forward)
 
     def set_frameon(self, b):
         """
-        Set whether the figure frame (background) is displayed or invisible
+        Set whether the figure frame (background) is displayed or invisible.
 
         ACCEPTS: boolean
         """
@@ -2079,7 +2103,7 @@ def subplots_adjust(self, *args, **kwargs):
         Call signature::
 
           subplots_adjust(left=None, bottom=None, right=None, top=None,
-                              wspace=None, hspace=None)
+                          wspace=None, hspace=None)
 
         Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
         *None*) and update the subplot locations.
@@ -2180,8 +2204,8 @@ def get_tightbbox(self, renderer):
         """
         Return a (tight) bounding box of the figure in inches.
 
-        It only accounts axes title, axis labels, and axis
-        ticklabels. Needs improvement.
+        Currently, this takes only axes title, axis labels, and axis
+        ticklabels into account. Needs improvement.
         """
 
         bb = []
@@ -2437,30 +2461,50 @@ def align_labels(self, axs=None):
 
 def figaspect(arg):
     """
-    Create a figure with specified aspect ratio.  If *arg* is a number,
-    use that aspect ratio.  If *arg* is an array, figaspect will
-    determine the width and height for a figure that would fit array
-    preserving aspect ratio.  The figure width, height in inches are
-    returned.  Be sure to create an axes with equal with and height,
-    e.g.,
-
-    Example usage::
-
-      # make a figure twice as tall as it is wide
-      w, h = figaspect(2.)
-      fig = Figure(figsize=(w,h))
-      ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
-      ax.imshow(A, **kwargs)
-
-
-      # make a figure with the proper aspect for an array
-      A = rand(5,3)
-      w, h = figaspect(A)
-      fig = Figure(figsize=(w,h))
-      ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
-      ax.imshow(A, **kwargs)
-
-    Thanks to Fernando Perez for this function
+    Calculate the width and height for a figure with a specified aspect ratio.
+
+    While the height is taken from :rc:`figure.figsize`, the width is
+    adjusted to match the desired aspect ratio. Additionally, it is ensured
+    that the width is in the range [4., 16.] and the height is in the range
+    [2., 16.]. If necessary, the default height is adjusted to ensure this.
+
+    Parameters
+    ----------
+    arg : scalar or 2d array
+        If a scalar, this defines the aspect ratio (i.e. the ratio height /
+        width).
+        In case of an array the aspect ratio is number of rows / number of
+        columns, so that the array could be fitted in the figure undistorted.
+
+    Returns
+    -------
+    width, height
+        The figure size in inches.
+
+    Notes
+    -----
+    If you want to create an axes within the figure, that still presevers the
+    aspect ratio, be sure to create it with equal width and height. See
+    examples below.
+
+    Thanks to Fernando Perez for this function.
+
+    Examples
+    --------
+    Make a figure twice as tall as it is wide::
+
+        w, h = figaspect(2.)
+        fig = Figure(figsize=(w, h))
+        ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
+        ax.imshow(A, **kwargs)
+
+    Make a figure with the proper aspect for an array::
+
+        A = rand(5,3)
+        w, h = figaspect(A)
+        fig = Figure(figsize=(w, h))
+        ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
+        ax.imshow(A, **kwargs)
     """
 
     isarray = hasattr(arg, 'shape') and not np.isscalar(arg)
