DOC: update Figure.savefig signature and re-order docstring

tacaswell · tacaswell · commit d0439771eadb · 2021-05-13T22:04:36.000-04:00
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2837,10 +2837,11 @@ def savefig(self, fname, *, transparent=None, **kwargs):
 
         Call signature::
 
-          savefig(fname, dpi=None, facecolor='w', edgecolor='w',
-                  orientation='portrait', papertype=None, format=None,
-                  transparent=False, bbox_inches=None, pad_inches=0.1,
-                  frameon=None, metadata=None)
+          savefig(fname, *, dpi='figure', format=None, metadata=None,
+                  bbox_inches=None, pad_inches=0.1,
+                  facecolor='auto', edgecolor='auto',
+                  backend=None, **kwargs
+                 )
 
         The available output formats depend on the backend being used.
 
@@ -2868,6 +2869,29 @@ def savefig(self, fname, *, transparent=None, **kwargs):
             The resolution in dots per inch.  If 'figure', use the figure's
             dpi value.
 
+        format : str
+            The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when
+            this is unset is documented under *fname*.
+
+        metadata : dict, optional
+            Key/value pairs to store in the image metadata. The supported keys
+            and defaults depend on the image format and backend:
+
+            - 'png' with Agg backend: See the parameter ``metadata`` of
+              `~.FigureCanvasAgg.print_png`.
+            - 'pdf' with pdf backend: See the parameter ``metadata`` of
+              `~.backend_pdf.PdfPages`.
+            - 'svg' with svg backend: See the parameter ``metadata`` of
+              `~.FigureCanvasSVG.print_svg`.
+            - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
+
+        bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox`
+            Bounding box in inches: only the given portion of the figure is
+            saved.  If 'tight', try to figure out the tight bbox of the figure.
+
+        pad_inches : float, default: :rc:`savefig.pad_inches`
+            Amount of padding around the figure when bbox_inches is 'tight'.
+
         facecolor : color or 'auto', default: :rc:`savefig.facecolor`
             The facecolor of the figure.  If 'auto', use the current figure
             facecolor.
@@ -2876,6 +2900,14 @@ def savefig(self, fname, *, transparent=None, **kwargs):
             The edgecolor of the figure.  If 'auto', use the current figure
             edgecolor.
 
+        backend : str, optional
+            Use a non-default backend to render the file, e.g. to render a
+            png file with the "cairo" backend rather than the default "agg",
+            or a pdf file with the "pgf" backend rather than the default
+            "pdf".  Note that the default backend is normally sufficient.  See
+            :ref:`the-builtin-backends` for a list of valid backends for each
+            file format.  Custom backends can be referenced as "module://...".
+
         orientation : {'landscape', 'portrait'}
             Currently only supported by the postscript backend.
 
@@ -2884,57 +2916,30 @@ def savefig(self, fname, *, transparent=None, **kwargs):
             'a10', 'b0' through 'b10'. Only supported for postscript
             output.
 
-        format : str
-            The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when
-            this is unset is documented under *fname*.
-
         transparent : bool
             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.
+            Figure patch will also be transparent unless *facecolor*
+            and/or *edgecolor* are specified via kwargs.
 
-            If *False* has no effect and leaves the color of the Axes and
-            Figure patches as they are.
+            If *False* has no effect and the color of the Axes and
+            Figure patches are unchanged (unless the Figure patch
+            is specified via the *facecolor* and/or *edgecolor* keyword
+            arguments in which case those colors are used).
 
-            This is useful, for example, for displaying
-            a plot on top of a colored background on a web page.  The
-            transparency of these patches will be restored to their
+            The transparency of these patches will be restored to their
             original values upon exit of this function.
 
-        bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox`
-            Bounding box in inches: only the given portion of the figure is
-            saved.  If 'tight', try to figure out the tight bbox of the figure.
-
-        pad_inches : float, default: :rc:`savefig.pad_inches`
-            Amount of padding around the figure when bbox_inches is 'tight'.
+            This is useful, for example, for displaying
+            a plot on top of a colored background on a web page.
 
         bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional
             A list of extra artists that will be considered when the
             tight bbox is calculated.
 
-        backend : str, optional
-            Use a non-default backend to render the file, e.g. to render a
-            png file with the "cairo" backend rather than the default "agg",
-            or a pdf file with the "pgf" backend rather than the default
-            "pdf".  Note that the default backend is normally sufficient.  See
-            :ref:`the-builtin-backends` for a list of valid backends for each
-            file format.  Custom backends can be referenced as "module://...".
-
-        metadata : dict, optional
-            Key/value pairs to store in the image metadata. The supported keys
-            and defaults depend on the image format and backend:
-
-            - 'png' with Agg backend: See the parameter ``metadata`` of
-              `~.FigureCanvasAgg.print_png`.
-            - 'pdf' with pdf backend: See the parameter ``metadata`` of
-              `~.backend_pdf.PdfPages`.
-            - 'svg' with svg backend: See the parameter ``metadata`` of
-              `~.FigureCanvasSVG.print_svg`.
-            - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
-
         pil_kwargs : dict, optional
             Additional keyword arguments that are passed to
             `PIL.Image.Image.save` when saving the figure.
+
         """
 
         kwargs.setdefault('dpi', mpl.rcParams['savefig.dpi'])
