DOC: Add sections to rcParams documentation

Author: timhoffm

doc/sphinxext/rcparams.py

@@ -19,15 +19,26 @@ def run(self):
         self.state.document.settings.env.note_dependency(__file__)
         self.state.document.settings.env.note_dependency(rcsetup.__file__)
         lines = []
-        for param in rcsetup._params:
-            if param.name[0] == '_':
-                continue
-            lines += [
-                f'.. _rcparam_{param.name.replace(".", "_")}:',
-                '',
-                f'{param.name}: ``{param.default!r}``',
-                f'    {param.description if param.description else "*no description*"}'
-            ]
+        for elem in rcsetup._DEFINITION:
+            if isinstance(elem, (rcsetup._Section, rcsetup._Subsection)):
+                title_char = '-' if isinstance(elem, rcsetup._Section) else '~'
+                lines += [
+                    '',
+                    elem.title,
+                    title_char * len(elem.title),
+                    '',
+                    elem.description or "",
+                    '',
+                ]
+            elif isinstance(elem, rcsetup._Param):
+                if elem.name[0] == '_':
+                    continue
+                lines += [
+                    f'.. _rcparam_{elem.name.replace(".", "_")}:',
+                    '',
+                    f'{elem.name}: ``{elem.default!r}``',
+                    f'   {elem.description if elem.description else "*no description*"}'
+                ]
         self.state_machine.insert_input(lines, 'rcParams table')
         return []
 

lib/matplotlib/rcsetup.py

@@ -1450,7 +1450,33 @@ class _Param:
     description: str = None
 
 
-_params = [
+@dataclass
+class _Section:
+    title: str
+    description: str = None
+
+
+@dataclass
+class _Subsection:
+    title: str
+    description: str = None
+
+
+# Definition of all rcParams. This is currently only used to generate the documentation.
+#
+# Actual runtime values do still come from the historic sources:
+# - available parameters and defaults: lib/matplotlib/mpl-data/matplotlibrc
+# - validators: _validators, see above
+#
+# The structure and format of this definition is not fixed and may change in the future.
+# It's a work-in-progress state towards a consistent and more structured definition of
+# rcParams that can be used both for documentation and runtime. The goal is to
+# eventually eliminate the old sources of defaults and validators and have this be the
+# single source of truth.
+#
+# In the transition phase, consistency is ensured via tests.
+_DEFINITION = [
+    _Section("Backends"),
     _Param(
         "webagg.port",
         default=8988,
@@ -1507,6 +1533,11 @@ class _Param:
         validator=validate_string,
         description="a pytz timezone string, e.g., US/Central or Europe/Paris"
     ),
+    _Section(
+        "Lines",
+        description="Default properties for line objects, such as those returned by "
+                    "plot()."
+    ),
     _Param(
         "lines.linewidth",
         default=1.5,
@@ -1627,6 +1658,7 @@ class _Param:
                     "solely to allow old test images to remain unchanged. Set to False "
                     "to obtain the previous behavior."
     ),
+    _Section("Patches"),
     _Param(
         "patch.linewidth",
         default=1.0,
@@ -1661,8 +1693,10 @@ class _Param:
         validator=validate_bool,
         description="render patches in antialiased (no jaggies)"
     ),
+    _Section("Hatches"),
     _Param("hatch.color", "edge", _validate_color_or_edge),
     _Param("hatch.linewidth", 1.0, validate_float),
+    _Section("Boxplot"),
     _Param("boxplot.notch", False, validate_bool),
     _Param("boxplot.vertical", True, validate_bool),
     _Param("boxplot.whiskers", 1.5, validate_whiskers),
@@ -1700,6 +1734,13 @@ class _Param:
     _Param("boxplot.meanprops.markersize", 6.0, validate_float),
     _Param("boxplot.meanprops.linestyle", "--", _validate_linestyle),
     _Param("boxplot.meanprops.linewidth", 1.0, validate_float),
+    _Section(
+        "Font",
+        description="The font properties used by `text.Text` "
+                    "See https://matplotlib.org/stable/api/font_manager_api.html for "
+                    "more information on font properties. The 6 font properties used "
+                    "for font matching are given below with their default values."
+    ),
     _Param("font.family", ["sans-serif"], validate_stringlist),
     _Param("font.style", "normal", validate_string),
     _Param("font.variant", "normal", validate_string),
@@ -1755,6 +1796,7 @@ class _Param:
                     "appended to all font selections. This ensures that there will "
                     "always be a glyph displayed."
     ),
+    _Section("Text properties"),
     _Param(
         "text.color",
         default="black",
@@ -1808,6 +1850,7 @@ class _Param:
         description="Use mathtext if there is an even number of unescaped dollar signs."
 
     ),
+    _Section("Mathtext and LaTeX"),
     _Param(
         "text.usetex",
         default=False,
@@ -1866,6 +1909,7 @@ class _Param:
                     'names, including the special name "regular" for the same font '
                     'used in regular text.',
            ),
+    _Section("Axes"),
     _Param(
         "axes.facecolor",
         default="white",
@@ -2077,12 +2121,14 @@ class _Param:
                     '"round_numbers", after application of margins, axis limits are '
                     'further expanded to the nearest "round" number.',
     ),
+    _Subsection("Polar Axes"),
     _Param(
         "polaraxes.grid",
         default=True,
         validator=validate_bool,
         description="display grid on polar axes"
     ),
+    _Subsection("3D Axes"),
     _Param(
         "axes3d.grid",
         default=True,
@@ -2143,6 +2189,7 @@ class _Param:
         description="trackball border width, in units of the Axes bbox (only for "
                     "'sphere' and 'arcball' style)"
     ),
+    _Section("Axis"),
     _Param(
         "xaxis.labellocation",
         default="center",
@@ -2155,6 +2202,14 @@ class _Param:
         validator=["bottom", "center", "top"],
         description="alignment of the yaxis label: {bottom, top, center}"
     ),
+    _Section(
+        "Dates",
+        description="Default properties for date tick labels. These are used by the "
+                    "`.AutoDateFormatter` when the appropriate time unit is detected."
+                    "See "
+                    "https://matplotlib.org/stable/api/dates_api.html#date-formatters "
+                    "for more information."
+    ),
     _Param("date.autoformatter.year", "%Y", validate_string),
     _Param("date.autoformatter.month", "%Y-%m", validate_string),
     _Param("date.autoformatter.day", "%Y-%m-%d", validate_string),
@@ -2180,6 +2235,7 @@ class _Param:
         validator=validate_bool,
         description="For auto converter whether to use interval_multiples"
     ),
+    _Section("Ticks"),
     _Param(
         "xtick.top",
         default=False,
@@ -2430,6 +2486,7 @@ class _Param:
            ["center", "top", "bottom", "baseline", "center_baseline"],
            description="alignment of yticks"
            ),
+    _Section("Grid"),
     _Param(
         "grid.color",
         default="#b0b0b0",
@@ -2502,6 +2559,7 @@ class _Param:
         validator=validate_float_or_None,
         description="If None defaults to grid.alpha"
     ),
+    _Section("Legend"),
     _Param(
         "legend.loc",
         default="best",
@@ -2626,6 +2684,7 @@ class _Param:
         default=2.0,
         validator=validate_float, description="column separation"
     ),
+    _Section("Figure"),
     _Param(
         "figure.titlesize",
         default="large",
@@ -2777,6 +2836,7 @@ class _Param:
                     "figure.subplot.wspace) as constrained_layout already takes "
                     "surrounding texts (titles, labels, # ticklabels) into account."
     ),
+    _Section("Images"),
     _Param(
         "image.aspect",
         default="equal",
@@ -2825,6 +2885,7 @@ class _Param:
                     "single composite image before saving a figure as a vector "
                     "graphics file, such as a PDF."
     ),
+    _Section("Contour plots"),
     _Param(
         "contour.negative_linestyle",
         default="dashed",
@@ -2849,18 +2910,21 @@ class _Param:
         validator=["mpl2005", "mpl2014", "serial", "threaded"],
         description="{mpl2005, mpl2014, serial, threaded}"
     ),
+    _Section("Errorbar plots"),
     _Param(
         "errorbar.capsize",
         default=0.0,
         validator=validate_float,
         description="length of end cap on error bars in pixels"
     ),
+    _Section("Histogram plots"),
     _Param(
         "hist.bins",
         default=10,
         validator=validate_hist_bins,
         description="The default number of histogram bins or 'auto'."
     ),
+    _Section("Scatter plots"),
     _Param(
         "scatter.marker",
         default="o",
@@ -2873,6 +2937,7 @@ class _Param:
         validator=validate_string,
         description="The default edge colors for scatter plots."
     ),
+    _Section("AGG rendering"),
     _Param(
         "agg.path.chunksize",
         default=0,
@@ -2883,6 +2948,7 @@ class _Param:
                     "cause minor artifacts, though. A value of 20000 is probably a "
                     "good starting point."
     ),
+    _Section("Paths"),
     _Param(
         "path.simplify",
         default=True,
@@ -2922,6 +2988,7 @@ class _Param:
         default=[],
         validator=validate_anylist
     ),
+    _Section("Saving figures"),
     _Param(
         "savefig.dpi",
         default="figure",
@@ -2980,19 +3047,22 @@ class _Param:
         validator=["landscape", "portrait"],
         description="orientation of saved figure, for PostScript output only"
     ),
+    _Subsection("Mac OSX backend parameters"),
     _Param(
         "macosx.window_mode",
         default="system",
         validator=["system", "tab", "window"],
         description="How to open new figures (system, tab, window) system uses "
                     "the MacOS system preferences"
     ),
+    _Subsection("Tk backend parameters"),
     _Param(
         "tk.window_focus",
         default=False,
         validator=validate_bool,
         description="Maintain shell focus for TkAgg"
     ),
+    _Subsection("PS backend parameters"),
     _Param(
         "ps.papersize",
         default="letter",
@@ -3028,6 +3098,7 @@ class _Param:
         validator=validate_fonttype,
         description="Output Type 3 (Type3) or Type 42 (TrueType)"
     ),
+    _Subsection("PDF backend parameters"),
     _Param(
         "pdf.compression",
         default=6,
@@ -3050,6 +3121,7 @@ class _Param:
         default=False,
         validator=validate_bool
     ),
+    _Subsection("SVG backend parameters"),
     _Param(
         "svg.image_inline",
         default=True,
@@ -3079,6 +3151,7 @@ class _Param:
         description="If not None, use this string as the value for the `id` attribute "
                     "in the top <svg> tag"
     ),
+    _Subsection("PGF parameters"),
     _Param(
         "pgf.rcfonts",
         default=True,
@@ -3095,12 +3168,18 @@ class _Param:
         default="xelatex",
         validator=["xelatex", "lualatex", "pdflatex"]
     ),
+    _Subsection("Docstring parameters"),
     _Param(
         "docstring.hardcopy",
         default=False,
         validator=validate_bool,
         description="set this when you want to generate hardcopy docstring"
     ),
+    _Section(
+        "Interactive keymaps",
+        description="Default key mappings for interactive navigation. See "
+                    ":ref:`key-event-handling`."
+    ),
     _Param(
         "keymap.fullscreen",
         default=["f", "ctrl+f"],
@@ -3187,6 +3266,7 @@ class _Param:
         validator=validate_stringlist,
         description="copy figure to clipboard"
     ),
+    _Section("Animation"),
     _Param(
         "animation.html",
         default="none",
@@ -3260,3 +3340,7 @@ class _Param:
     ),
     _Param("backend", None, validate_backend),
 ]
+
+
+def _params_list():
+    return [elem for elem in _DEFINITION if isinstance(elem, _Param)]

lib/matplotlib/tests/test_rcparams.py

@@ -676,17 +676,17 @@ def test_rc_aliases(group, option, alias, value):
 
 
 def test_all_params_defined_as_code():
-    assert set(p.name for p in rcsetup._params) == set(mpl.rcParams.keys())
+    assert set(p.name for p in rcsetup._params_list()) == set(mpl.rcParams.keys())
 
 
 def test_validators_defined_as_code():
-    for param in rcsetup._params:
+    for param in rcsetup._params_list():
         validator = rcsetup._convert_validator_spec(param.name, param.validator)
         assert validator == rcsetup._validators[param.name]
 
 
 def test_defaults_as_code():
-    for param in rcsetup._params:
+    for param in rcsetup._params_list():
         if param.name == 'backend':
             # backend has special handling and no meaningful default
             continue