port some figure docstrings to numpydoc

timhoffm · timhoffm · commit 6673184c4e95 · 2017-11-14T01:07:06.000+01:00
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -884,20 +884,20 @@ def add_axes(self, *args, **kwargs):
         rect : sequence of float
             A 4-length sequence of [left, bottom, width, height] quantities.
 
-        projection :
-            ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
-'polar' | 'rectilinear'], optional
+        projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \
+        'polar', 'rectilinear'}, optional
             The projection type of the axes.
 
         polar : boolean, optional
             If True, equivalent to projection='polar'.
 
-        This method also takes the keyword arguments for
-        :class:`~matplotlib.axes.Axes`.
+        **kwargs
+            This method also takes the keyword arguments for
+            :class:`~.axes.Axes`.
 
         Returns
-        ------
-        axes : Axes
+        -------
+        axes : :class:`~.axes.Axes`
             The added axes.
 
         Examples
@@ -987,19 +987,20 @@ def add_subplot(self, *args, **kwargs):
             integers are I, J, and K, the subplot is the Ith plot on a
             grid with J rows and K columns.
 
-        projection : ['aitoff' | 'hammer' | 'lambert' | \
-'mollweide' | 'polar' | 'rectilinear'], optional
+        projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \
+        'polar', 'rectilinear'}, optional
             The projection type of the axes.
 
         polar : boolean, optional
             If True, equivalent to projection='polar'.
 
-        This method also takes the keyword arguments for
-        :class:`~matplotlib.axes.Axes`.
+        **kwargs
+            This method also takes the keyword arguments for
+            :class:`~matplotlib.axes.Axes`.
 
         Returns
         -------
-        axes : Axes
+        axes : :class:`~matplotlib.axes.Axes`
             The axes of the subplot.
 
         Notes
@@ -1010,6 +1011,8 @@ def add_subplot(self, *args, **kwargs):
 
         Examples
         --------
+        ::
+
             fig.add_subplot(111)
 
             # equivalent but more general
@@ -1440,22 +1443,22 @@ def legend(self, *args, **kwargs):
             If shadow is activated and framealpha is ``None`` the
             default value is being ignored.
 
-        facecolor : None or "inherit" or a color spec
+        facecolor : None or 'inherit' or a color spec
             Control the legend's background color.
             Default is ``None`` which will take the value from the
             ``legend.facecolor`` :data:`rcParam<matplotlib.rcParams>`.
-            If ``"inherit"``, it will take the ``axes.facecolor``
+            If ``'inherit'``, it will take the ``axes.facecolor``
             :data:`rcParam<matplotlib.rcParams>`.
 
-        edgecolor : None or "inherit" or a color spec
+        edgecolor : None or 'inherit' or a color spec
             Control the legend's background patch edge color.
             Default is ``None`` which will take the value from the
             ``legend.edgecolor`` :data:`rcParam<matplotlib.rcParams>`.
-            If ``"inherit"``, it will take the ``axes.edgecolor``
+            If ``'inherit'``, it will take the ``axes.edgecolor``
             :data:`rcParam<matplotlib.rcParams>`.
 
-        mode : {"expand", None}
-            If `mode` is set to ``"expand"`` the legend will be horizontally
+        mode : {'expand', None}
+            If `mode` is set to ``'expand'`` the legend will be horizontally
             expanded to fill the axes area (or `bbox_to_anchor` if defines
             the legend's size).
 
@@ -1734,9 +1737,10 @@ def savefig(self, fname, **kwargs):
 
         The output formats available depend on the backend being used.
 
-        Arguments:
+        Parameters
+        ----------
 
-          *fname*:
+        fname : str or file-like object
             A string containing a path to a filename, or a Python
             file-like object, or possibly some backend-dependent object
             such as :class:`~matplotlib.backends.backend_pdf.PdfPages`.
@@ -1749,29 +1753,33 @@ def savefig(self, fname, **kwargs):
             If *fname* is not a string, remember to specify *format* to
             ensure that the correct backend is used.
 
-        Keyword arguments:
+        Other Parameters
+        ----------------
 
-          *dpi*: [ *None* | ``scalar > 0`` | 'figure']
+        dpi : [ *None* | scalar > 0 | 'figure']
             The resolution in dots per inch.  If *None* it will default to
             the value ``savefig.dpi`` in the matplotlibrc file. If 'figure'
             it will set the dpi to be the value of the figure.
 
-          *facecolor*, *edgecolor*:
-            the colors of the figure rectangle
+        facecolor : color spec or None, optional
+            the facecolor of the figure; if None, defaults to savefig.facecolor
 
-          *orientation*: [ 'landscape' | 'portrait' ]
+        edgecolor : color spec or None, optional
+            the edgecolor of the figure; if None, defaults to savefig.edgecolor
+
+        orientation : {'landscape', 'portrait'}
             not supported on all backends; currently only on postscript output
 
-          *papertype*:
+        papertype : str
             One of 'letter', 'legal', 'executive', 'ledger', 'a0' through
             'a10', 'b0' through 'b10'. Only supported for postscript
             output.
 
-          *format*:
+        format : str
             One of the file extensions supported by the active
             backend.  Most backends support png, pdf, ps, eps and svg.
 
-          *transparent*:
+        transparent : {True, False}
             If *True*, the axes patches will all be transparent; the
             figure patch will also be transparent unless facecolor
             and/or edgecolor are specified via kwargs.
@@ -1780,21 +1788,21 @@ def savefig(self, fname, **kwargs):
             transparency of these patches will be restored to their
             original values upon exit of this function.
 
-          *frameon*:
+        frameon : {True, False}
             If *True*, the figure patch will be colored, if *False*, the
             figure background will be transparent.  If not provided, the
             rcParam 'savefig.frameon' will be used.
 
-          *bbox_inches*:
+        bbox_inches : str or `~matplotlib.transforms.Bbox`, optional
             Bbox in inches. Only the given portion of the figure is
             saved. If 'tight', try to figure out the tight bbox of
-            the figure.
+            the figure. If None, use savefig.bbox
 
-          *pad_inches*:
+        pad_inches : scalar, optional
             Amount of padding around the figure when bbox_inches is
-            'tight'.
+            'tight'. If None, use savefig.pad_inches
 
-          *bbox_extra_artists*:
+        bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional
             A list of extra artists that will be considered when the
             tight bbox is calculated.
 
@@ -1988,17 +1996,20 @@ def tight_layout(self, renderer=None, pad=1.08, h_pad=None, w_pad=None,
         """
         Adjust subplot parameters to give specified padding.
 
-        Parameters:
+        Parameters
+        ----------
 
-          pad : float
+        pad : float
             padding between the figure edge and the edges of subplots,
             as a fraction of the font-size.
-          h_pad, w_pad : float
+
+        h_pad, w_pad : float, optional
             padding (height/width) between edges of adjacent subplots.
             Defaults to `pad_inches`.
-          rect : if rect is given, it is interpreted as a rectangle
-            (left, bottom, right, top) in the normalized figure
-            coordinate that the whole subplots area (including
+
+        rect : tuple (left, bottom, right, top), optional
+            a rectangle (left, bottom, right, top) in the normalized
+            figure coordinate that the whole subplots area (including
             labels) will fit into. Default is (0, 0, 1, 1).
         """
 
