Merge pull request matplotlib#17162 from timhoffm/doc-rc-context

Update docs of rc_context()

Author: QuLogic

lib/matplotlib/__init__.py

@@ -842,7 +842,7 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
     Parameters
     ----------
     fname : str or path-like
-        Name of file parsed for Matplotlib settings.
+        A file with Matplotlib rc settings.
     fail_on_error : bool
         If True, raise an error when the parser fails to convert a parameter.
     use_default_template : bool
@@ -1019,8 +1019,8 @@ def rc_file(fname, *, use_default_template=True):
 
     Parameters
     ----------
-    fname : str
-        Name of file parsed for matplotlib settings.
+    fname : str or path-like
+        A file with Matplotlib rc settings.
 
     use_default_template : bool
         If True, initialize with default parameters before updating with those
@@ -1040,29 +1040,35 @@ def rc_file(fname, *, use_default_template=True):
 @contextlib.contextmanager
 def rc_context(rc=None, fname=None):
     """
-    Return a context manager for managing rc settings.
-
-    This allows one to do::
+    Return a context manager for temporarily changing rcParams.
 
-        with mpl.rc_context(fname='screen.rc'):
-            plt.plot(x, a)  # uses 'screen.rc'
-            with mpl.rc_context(fname='print.rc'):
-                plt.plot(x, b)  # uses 'print.rc'
-            plt.plot(x, c)  # uses 'screen.rc'
-
-    A dictionary can also be passed to the context manager::
+    Parameters
+    ----------
+    rc : dict
+        The rcParams to temporarily set.
+    fname : str or path-like
+        A file with Matplotlib rc settings. If both *fname* and *rc* are given,
+        settings from *rc* take precedence.
 
-        with mpl.rc_context(rc={'text.usetex': True}, fname='screen.rc'):
-            plt.plot(x, a)
+    See Also
+    --------
+    :ref:`customizing-with-matplotlibrc-files`
 
-    The *rc* dictionary takes precedence over the settings loaded from *fname*.
-    Passing a dictionary only is also valid.  For example, a common usage is::
+    Examples
+    --------
+    Passing explicit values via a dict::
 
         with mpl.rc_context({'interactive': False}):
             fig, ax = plt.subplots()
             ax.plot(range(3), range(3))
-            fig.savefig('A.png', format='png')
+            fig.savefig('example.png')
             plt.close(fig)
+
+    Loading settings from a file::
+
+         with mpl.rc_context(fname='print.rc'):
+             plt.plot(x, y)  # uses 'print.rc'
+
     """
     orig = rcParams.copy()
     try:

lib/matplotlib/backends/backend_agg.py

@@ -439,7 +439,7 @@ def print_png(self, filename_or_obj, *args,
 
         Parameters
         ----------
-        filename_or_obj : str or PathLike or file-like object
+        filename_or_obj : str or path-like or file-like
             The file to write to.
 
         metadata : dict, optional
@@ -526,7 +526,7 @@ def print_jpg(self, filename_or_obj, *args, dryrun=False, pil_kwargs=None,
 
         Parameters
         ----------
-        filename_or_obj : str or PathLike or file-like object
+        filename_or_obj : str or path-like or file-like
             The file to write to.
 
         Other Parameters

lib/matplotlib/cbook/__init__.py

@@ -378,7 +378,7 @@ def to_filehandle(fname, flag='r', return_opened=False, encoding=None):
 
     Parameters
     ----------
-    fname : str or path-like or file-like object
+    fname : str or path-like or file-like
         If `str` or `os.PathLike`, the file is opened using the flags specified
         by *flag* and *encoding*.  If a file-like object, it is passed through.
     flag : str, default 'r'

lib/matplotlib/figure.py

@@ -2049,7 +2049,7 @@ def savefig(self, fname, *, transparent=None, **kwargs):
 
         Parameters
         ----------
-        fname : str or PathLike or file-like object
+        fname : str or path-like or file-like
             A path, or a Python file-like object, or
             possibly some backend-dependent object such as
             `matplotlib.backends.backend_pdf.PdfPages`.

lib/matplotlib/image.py

@@ -1475,7 +1475,7 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None,
 
     Parameters
     ----------
-    fname : str or PathLike or file-like
+    fname : str or path-like or file-like
         A path or a file-like object to store the image in.
         If *format* is not set, then the output format is inferred from the
         extension of *fname*, if any, and from :rc:`savefig.format` otherwise.