Improve markup for rcParams in docs.

anntzer · anntzer · commit a9db3e145a29 · 2020-01-21T21:36:49.000+01:00
... and deleted examples/color/color_cycler which is an exact duplicate
of tutorials/intermediate/color_cycle, except that the latter has been
further worked on.
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -109,7 +109,7 @@ begin with ``"test_"`` and then within those files for functions beginning with
 ``"test"`` or classes beginning with ``"Test"``.
 
 Some tests have internal side effects that need to be cleaned up after their
-execution (such as created figures or modified rc params). The pytest fixture
+execution (such as created figures or modified `.rcParams`). The pytest fixture
 :func:`~matplotlib.testing.conftest.mpl_test_settings` will automatically clean
 these up; there is no need to do anything further.
 
diff --git a/examples/color/color_cycler.py b/examples/color/color_cycler.py
diff --git a/examples/misc/customize_rc.py b/examples/misc/customize_rc.py
@@ -4,7 +4,7 @@
 ============
 
 I'm not trying to make a good looking figure here, but just to show
-some examples of customizing rc params on the fly
+some examples of customizing `.rcParams` on the fly.
 
 If you like to work interactively, and need to create different sets
 of defaults for figures (e.g., one set of defaults for publication, one
@@ -25,8 +25,8 @@ def set_pub():
     >>> plot([1, 2, 3])
     >>> savefig('myfig')
     >>> rcdefaults()  # restore the defaults
-
 """
+
 import matplotlib.pyplot as plt
 
 plt.subplot(311)
diff --git a/examples/style_sheets/grayscale.py b/examples/style_sheets/grayscale.py
@@ -4,10 +4,10 @@
 =====================
 
 This example demonstrates the "grayscale" style sheet, which changes all colors
-that are defined as rc parameters to grayscale. Note, however, that not all
-plot elements default to colors defined by an rc parameter.
-
+that are defined as `.rcParams` to grayscale. Note, however, that not all
+plot elements respect `.rcParams`.
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -873,15 +873,15 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True):
 
 def rc(group, **kwargs):
     """
-    Set the current rc params.  *group* is the grouping for the rc, e.g.,
+    Set the current `.rcParams`.  *group* is the grouping for the rc, e.g.,
     for ``lines.linewidth`` the group is ``lines``, for
     ``axes.facecolor``, the group is ``axes``, and so on.  Group may
     also be a list or tuple of group names, e.g., (*xtick*, *ytick*).
     *kwargs* is a dictionary attribute name/value pairs, e.g.,::
 
       rc('lines', linewidth=2, color='r')
 
-    sets the current rc params and is equivalent to::
+    sets the current `.rcParams` and is equivalent to::
 
       rcParams['lines.linewidth'] = 2
       rcParams['lines.color'] = 'r'
@@ -915,7 +915,7 @@ def rc(group, **kwargs):
 
     This enables you to easily switch between several configurations.  Use
     ``matplotlib.style.use('default')`` or :func:`~matplotlib.rcdefaults` to
-    restore the default rc params after changes.
+    restore the default `.rcParams` after changes.
 
     Notes
     -----
@@ -949,15 +949,16 @@ def rc(group, **kwargs):
 
 def rcdefaults():
     """
-    Restore the rc params from Matplotlib's internal default style.
+    Restore the `.rcParams` from Matplotlib's internal default style.
 
-    Style-blacklisted rc params (defined in
+    Style-blacklisted `.rcParams` (defined in
     `matplotlib.style.core.STYLE_BLACKLIST`) are not updated.
 
     See Also
     --------
     rc_file_defaults
-        Restore the rc params from the rc file originally loaded by Matplotlib.
+        Restore the `.rcParams` from the rc file originally loaded by
+        Matplotlib.
     matplotlib.style.use
         Use a specific style file.  Call ``style.use('default')`` to restore
         the default style.
@@ -973,9 +974,9 @@ def rcdefaults():
 
 def rc_file_defaults():
     """
-    Restore the rc params from the original rc file loaded by Matplotlib.
+    Restore the `.rcParams` from the original rc file loaded by Matplotlib.
 
-    Style-blacklisted rc params (defined in
+    Style-blacklisted `.rcParams` (defined in
     `matplotlib.style.core.STYLE_BLACKLIST`) are not updated.
     """
     # Deprecation warnings were already handled when creating rcParamsOrig, no
@@ -988,9 +989,9 @@ def rc_file_defaults():
 
 def rc_file(fname, *, use_default_template=True):
     """
-    Update rc params from file.
+    Update `.rcParams` from file.
 
-    Style-blacklisted rc params (defined in
+    Style-blacklisted `.rcParams` (defined in
     `matplotlib.style.core.STYLE_BLACKLIST`) are not updated.
 
     Parameters
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -1031,10 +1031,8 @@ def func(current_frame: int, total_frames: int) -> Any
         construct a `.MovieWriter` instance and can only be passed if
         *writer* is a string.  If they are passed as non-*None* and *writer*
         is a `.MovieWriter`, a `RuntimeError` will be raised.
-
         """
-        # If the writer is None, use the rc param to find the name of the one
-        # to use
+
         if writer is None:
             writer = mpl.rcParams['animation.writer']
         elif (not isinstance(writer, str) and
@@ -1263,8 +1261,8 @@ def to_html5_video(self, embed_limit=None):
         Convert the animation to an HTML5 ``<video>`` tag.
 
         This saves the animation as an h264 video, encoded in base64
-        directly into the HTML5 video tag. This respects the rc parameters
-        for the writer as well as the bitrate. This also makes use of the
+        directly into the HTML5 video tag. This respects :rc:`animation.writer`
+        and :rc:`animation.bitrate`. This also makes use of the
         ``interval`` to control the speed, and uses the ``repeat``
         parameter to decide whether to loop.
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -710,7 +710,7 @@ def text(self, x, y, s, fontdict=None, **kwargs):
 
         fontdict : dict, default: None
             A dictionary to override the default text properties. If fontdict
-            is None, the defaults are determined by your rc parameters.
+            is None, the defaults are determined by `.rcParams`.
 
         Returns
         -------
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -186,7 +186,7 @@ class LatexManager:
     """
     The LatexManager opens an instance of the LaTeX application for
     determining the metrics of text elements. The LaTeX environment can be
-    modified by setting fonts and/or a custom preamble in the rc parameters.
+    modified by setting fonts and/or a custom preamble in `.rcParams`.
     """
     _unclean_instances = weakref.WeakSet()
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1830,9 +1830,8 @@ def text(self, x, y, s, fontdict=None, **kwargs):
 
         fontdict : dict, optional
             A dictionary to override the default text properties. If not given,
-            the defaults are determined by your rc parameters. Properties
-            passed as *kwargs* override the corresponding ones given in
-            *fontdict*.
+            the defaults are determined by `.rcParams`. Properties passed as
+            *kwargs* override the corresponding ones given in *fontdict*.
 
         Other Parameters
         ----------------
diff --git a/tutorials/intermediate/color_cycle.py b/tutorials/intermediate/color_cycle.py
@@ -13,7 +13,7 @@
 
 This example demonstrates two different APIs:
 
-1. Setting the default rc parameter specifying the property cycle.
+1. Setting the rc parameter specifying the default property cycle.
    This affects all subsequent axes (but not axes already created).
 2. Setting the property cycle for a single pair of axes.
 
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -732,7 +732,7 @@ def my_plotter(ax, data1, data2, param_dict):
 # -----------------------------------
 #
 # If you are using the Agg backend (see :ref:`what-is-a-backend`),
-# then you can make use of the ``agg.path.chunksize`` rc parameter.
+# then you can make use of :rc:`agg.path.chunksize`
 # This allows you to specify a chunk size, and any lines with
 # greater than that many vertices will be split into multiple
 # lines, each of which has no more than ``agg.path.chunksize``
