PoC: Document each rcParam individually

Taking cues from the math symbol table, this adds a directive to
generate a listing from the `RcParams` dictionary, with types taken from
the validators (partially complete), though there could perhaps be other
ways to implement it. Then the `rc` role is updated to point to these
individual anchors.

We also have nowhere to put the documentation for each one yet, so the
actual information is all just stubs.

Author: QuLogic

doc/conf.py

@@ -124,8 +124,9 @@ def _parse_skip_subdirs_file():
     'sphinxext.math_symbol_table',
     'sphinxext.missing_references',
     'sphinxext.mock_gui_toolkits',
-    'sphinxext.skip_deprecated',
+    'sphinxext.rcparams',
     'sphinxext.redirect_from',
+    'sphinxext.skip_deprecated',
     'sphinx_copybutton',
     'sphinx_design',
     'sphinx_tags',

doc/sphinxext/rcparams.py

@@ -0,0 +1,62 @@
+import enum
+
+from docutils.parsers.rst import Directive
+
+from matplotlib import rcParams, rcParamsDefault, rcsetup
+
+
+def determine_type(validator):
+    if isinstance(validator, enum.EnumType):
+        return f'`~._enums.{validator.__name__}`'
+    elif docstr := getattr(validator, '__doc__'):
+        return docstr
+    else:
+        return str(validator)
+
+
+def run(state_machine):
+    lines = []
+    current_section = None
+    for rc in sorted(rcParams.keys()):
+        if rc[0] == '_':
+            continue
+
+        # This would be much easier with #25617.
+        section = rc.rsplit('.', maxsplit=1)[0]
+        if section != current_section:
+            lines.append(f'.. _rc-{section}:')
+            current_section = section
+
+        type_str = determine_type(rcsetup._validators[rc])
+        if rc in rcParamsDefault and rc != "backend":
+            default = f', default: {rcParamsDefault[rc]!r}'
+        else:
+            default = ''
+        lines += [
+            f'.. _rc-{rc}:',
+            '',
+            rc,
+            '^' * len(rc),
+            f'{type_str}{default}',
+            f'    Documentation for {rc}.'
+        ]
+    state_machine.insert_input(lines, "rcParams table")
+    return []
+
+
+class RcParamsDirective(Directive):
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        return run(self.state_machine)
+
+
+def setup(app):
+    app.add_directive("rcparams", RcParamsDirective)
+
+    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
+    return metadata

galleries/users_explain/customizing.py

@@ -108,10 +108,10 @@ def plotting_function():
 # ignored in style sheets see `matplotlib.style.use`.
 #
 # There are a number of pre-defined styles :doc:`provided by Matplotlib
-# </gallery/style_sheets/style_sheets_reference>`. For
-# example, there's a pre-defined style called "ggplot", which emulates the
-# aesthetics of ggplot_ (a popular plotting package for R_). To use this
-# style, add:
+# </gallery/style_sheets/style_sheets_reference>`. For example, there's a pre-defined
+# style called "ggplot", which emulates the aesthetics of `ggplot
+# <https://ggplot2.tidyverse.org/>`_ (a popular plotting package for `R
+# <https://www.r-project.org/>`_). To use this style, add:
 
 plt.style.use('ggplot')
 
@@ -259,11 +259,10 @@ def plotting_function():
 #
 # .. _matplotlibrc-sample:
 #
-# The default :file:`matplotlibrc` file
-# -------------------------------------
+# Available ``rcParams``
+# ----------------------
 #
-# .. literalinclude:: ../../../lib/matplotlib/mpl-data/matplotlibrc
+#
+# .. rcparams::
 #
 #
-# .. _ggplot: https://ggplot2.tidyverse.org/
-# .. _R: https://www.r-project.org/