DOC: Improve linkage between rcParams-related documentation

timhoffm · timhoffm · commit 8b4eb05b49c0 · 2026-01-10T01:24:42.000+01:00
Follow up to https://github .com//pull/30871#discussion_r2674234162.
diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst
@@ -24,8 +24,24 @@ Default values and styling
 ==========================
 
 .. py:data:: rcParams
+   :type: RcParams
+
+   The global configuration settings for Matplotlib.
+
+   This a dictionary-like variable that stores the current configuration
+   settings.  Many of the values control styling, but others control
+   various aspects of Matplotlib's behavior.
+
+   See :doc:`/users/explain/configuration` for a full list of config
+   parameters.
+
+   See :ref:`customizing` for usage information.
+
+   Notes
+   -----
+   This object is also available as ``plt.rcParams`` via the
+   `matplotlib.pyplot` module (which by convention is imported as ``plt``).
 
-   An instance of `RcParams` for handling default Matplotlib values.
 
 .. autoclass:: RcParams
    :no-members:
diff --git a/galleries/users_explain/customizing.py b/galleries/users_explain/customizing.py
@@ -8,9 +8,12 @@
 Customizing Matplotlib with style sheets and rcParams
 =====================================================
 
-Tips for customizing the properties and default styles of Matplotlib.
+Many aspects of Matplotlib's behavior and default styles can be customized
+through the use of rc (runtime configuration) settings. The current values
+are stored in `~matplotlib.rcParams`.
 
-There are three ways to customize Matplotlib:
+There are three ways to customize Matplotlib, all of which effectively change
+`~matplotlib.rcParams`:
 
 1. :ref:`Setting rcParams at runtime<customizing-with-dynamic-rc-settings>`.
 2. :ref:`Using style sheets<customizing-with-style-sheets>`.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -131,7 +131,7 @@
     "colormaps",
     "multivar_colormaps",
     "bivar_colormaps",
-    "color_sequences",
+    "color_sequences"
 ]
 
 
@@ -158,7 +158,7 @@
 
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
-from . import _api, _version, cbook, _docstring, rcsetup
+from . import _api, _version, cbook, rcsetup
 from matplotlib._api import MatplotlibDeprecationWarning
 from matplotlib.colors import _color_sequences as color_sequences
 from matplotlib.rcsetup import cycler  # noqa: F401
@@ -658,23 +658,13 @@ def gen_candidates():
                        "install is broken")
 
 
-@_docstring.Substitution(
-    "\n".join(map("- {}".format, sorted(rcsetup._validators, key=str.lower)))
-)
 class RcParams(MutableMapping, dict):
     """
     A dict-like key-value store for config parameters, including validation.
 
-    Validating functions are defined and associated with rc parameters in
-    :mod:`matplotlib.rcsetup`.
+    This is the data structure behind `matplotlib.rcParams`.
 
-    The list of rcParams is:
-
-    %s
-
-    See Also
-    --------
-    :ref:`customizing-with-matplotlibrc-files`
+    The complete list of rcParams can be found in :doc:`/users/explain/configuration`.
     """
 
     validate = rcsetup._validators
