MNT: Cleanup docstring substitution mechanisms (matplotlib#28795)

* MNT: Make Substitution and _ArtistPropertiesSubstitution independent

They do not have relevant functional overlap. Thus, it's simpler
to keep them completely separated.

* Rename _ArtistPropertiesSubstitution.update() to register()

While it's internally a dict.update. The logical process is a
registration to make the names publically available. Also,
remove the possibility to pass a dict. Passing kwargs is
enough and we can simplify the API to only one type of usage.

Author: timhoffm

lib/matplotlib/_docstring.py

@@ -68,12 +68,6 @@ def __call__(self, func):
             func.__doc__ = inspect.cleandoc(func.__doc__) % self.params
         return func
 
-    def update(self, *args, **kwargs):
-        """
-        Update ``self.params`` (which must be a dict) with the supplied args.
-        """
-        self.params.update(*args, **kwargs)
-
 
 class _ArtistKwdocLoader(dict):
     def __missing__(self, key):
@@ -89,23 +83,45 @@ def __missing__(self, key):
         return self.setdefault(key, kwdoc(cls))
 
 
-class _ArtistPropertiesSubstitution(Substitution):
+class _ArtistPropertiesSubstitution:
     """
-    A `.Substitution` with two additional features:
-
-    - Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
-      literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
-      given *classname*, and are substituted with the `.kwdoc` of that class.
-    - Decorating a class triggers substitution both on the class docstring and
-      on the class' ``__init__`` docstring (which is a commonly required
-      pattern for Artist subclasses).
+    A class to substitute formatted placeholders in docstrings.
+
+    This is realized in a single instance ``_docstring.interpd``.
+
+    Use `~._ArtistPropertiesSubstition.register` to define placeholders and
+    their substitution, e.g. ``_docstring.interpd.register(name="some value")``.
+
+    Use this as a decorator to apply the substitution::
+
+        @_docstring.interpd
+        def some_func():
+            '''Replace %(name)s.'''
+
+    Decorating a class triggers substitution both on the class docstring and
+    on the class' ``__init__`` docstring (which is a commonly required
+    pattern for Artist subclasses).
+
+    Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
+    literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
+    given *classname*, and are substituted with the `.kwdoc` of that class.
     """
 
     def __init__(self):
         self.params = _ArtistKwdocLoader()
 
+    def register(self, **kwargs):
+        """
+        Register substitutions.
+
+        ``_docstring.interpd.register(name="some value")`` makes "name" available
+        as a named parameter that will be replaced by "some value".
+        """
+        self.params.update(**kwargs)
+
     def __call__(self, obj):
-        super().__call__(obj)
+        if obj.__doc__:
+            obj.__doc__ = inspect.cleandoc(obj.__doc__) % self.params
         if isinstance(obj, type) and obj.__init__ != object.__init__:
             self(obj.__init__)
         return obj

lib/matplotlib/_docstring.pyi

@@ -21,8 +21,9 @@ class _ArtistKwdocLoader(dict[str, str]):
     def __missing__(self, key: str) -> str: ...
 
 
-class _ArtistPropertiesSubstitution(Substitution):
+class _ArtistPropertiesSubstitution:
     def __init__(self) -> None: ...
+    def register(self, **kwargs) -> None: ...
     def __call__(self, obj: _T) -> _T: ...
 
 

lib/matplotlib/_enums.py

@@ -181,5 +181,7 @@ def demo():
         + ", ".join([f"'{cs.name}'" for cs in CapStyle]) \
         + "}"
 
-_docstring.interpd.update({'JoinStyle': JoinStyle.input_description,
-                          'CapStyle': CapStyle.input_description})
+_docstring.interpd.register(
+    JoinStyle=JoinStyle.input_description,
+    CapStyle=CapStyle.input_description,
+)

lib/matplotlib/axes/_secondary_axes.py

@@ -319,4 +319,4 @@ def set_color(self, color):
 **kwargs : `~matplotlib.axes.Axes` properties.
     Other miscellaneous Axes parameters.
 '''
-_docstring.interpd.update(_secax_docstring=_secax_docstring)
+_docstring.interpd.register(_secax_docstring=_secax_docstring)

lib/matplotlib/cm.py

@@ -651,7 +651,7 @@ def _format_cursor_data_override(self, data):
 
 
 # The docstrings here must be generic enough to apply to all relevant methods.
-mpl._docstring.interpd.update(
+mpl._docstring.interpd.register(
     cmap_doc="""\
 cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
     The Colormap instance or registered colormap name used to map scalar data

lib/matplotlib/colorbar.py

@@ -26,7 +26,7 @@
 
 _log = logging.getLogger(__name__)
 
-_docstring.interpd.update(
+_docstring.interpd.register(
     _make_axes_kw_doc="""
 location : None or {'left', 'right', 'top', 'bottom'}
     The location, relative to the parent Axes, where the colorbar Axes

lib/matplotlib/contour.py

@@ -536,7 +536,7 @@ def _find_closest_point_on_path(xys, p):
     return (d2s[imin], projs[imin], (imin, imin+1))
 
 
-_docstring.interpd.update(contour_set_attributes=r"""
+_docstring.interpd.register(contour_set_attributes=r"""
 Attributes
 ----------
 ax : `~matplotlib.axes.Axes`
@@ -1450,7 +1450,7 @@ def _initialize_x_y(self, z):
         return np.meshgrid(x, y)
 
 
-_docstring.interpd.update(contour_doc="""
+_docstring.interpd.register(contour_doc="""
 `.contour` and `.contourf` draw contour lines and filled contours,
 respectively.  Except as noted, function signatures and return values
 are the same for both versions.

lib/matplotlib/legend.py

@@ -305,7 +305,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
     _loc_doc_base.format(parent='axes', default=':rc:`legend.loc`',
                          best=_loc_doc_best, outside='') +
     _legend_kw_doc_base)
-_docstring.interpd.update(_legend_kw_axes=_legend_kw_axes_st)
+_docstring.interpd.register(_legend_kw_axes=_legend_kw_axes_st)
 
 _outside_doc = """
     If a figure is using the constrained layout manager, the string codes
@@ -323,20 +323,20 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
     _loc_doc_base.format(parent='figure', default="'upper right'",
                          best='', outside=_outside_doc) +
     _legend_kw_doc_base)
-_docstring.interpd.update(_legend_kw_figure=_legend_kw_figure_st)
+_docstring.interpd.register(_legend_kw_figure=_legend_kw_figure_st)
 
 _legend_kw_both_st = (
     _loc_doc_base.format(parent='axes/figure',
                          default=":rc:`legend.loc` for Axes, 'upper right' for Figure",
                          best=_loc_doc_best, outside=_outside_doc) +
     _legend_kw_doc_base)
-_docstring.interpd.update(_legend_kw_doc=_legend_kw_both_st)
+_docstring.interpd.register(_legend_kw_doc=_legend_kw_both_st)
 
 _legend_kw_set_loc_st = (
     _loc_doc_base.format(parent='axes/figure',
                          default=":rc:`legend.loc` for Axes, 'upper right' for Figure",
                          best=_loc_doc_best, outside=_outside_doc))
-_docstring.interpd.update(_legend_kw_set_loc_doc=_legend_kw_set_loc_st)
+_docstring.interpd.register(_legend_kw_set_loc_doc=_legend_kw_set_loc_st)
 
 
 class Legend(Artist):

lib/matplotlib/mlab.py

@@ -400,7 +400,7 @@ def _single_spectrum_helper(
 
 
 # Split out these keyword docs so that they can be used elsewhere
-_docstring.interpd.update(
+_docstring.interpd.register(
     Spectral="""\
 Fs : float, default: 2
     The sampling frequency (samples per time unit).  It is used to calculate

lib/matplotlib/patches.py

@@ -1552,7 +1552,7 @@ def _make_verts(self):
             ]
 
 
-_docstring.interpd.update(
+_docstring.interpd.register(
     FancyArrow="\n".join(
         (inspect.getdoc(FancyArrow.__init__) or "").splitlines()[2:]))
 
@@ -2290,7 +2290,7 @@ def __init_subclass__(cls):
         # - %(BoxStyle:table_and_accepts)s
         # - %(ConnectionStyle:table_and_accepts)s
         # - %(ArrowStyle:table_and_accepts)s
-        _docstring.interpd.update({
+        _docstring.interpd.register(**{
             f"{cls.__name__}:table": cls.pprint_styles(),
             f"{cls.__name__}:table_and_accepts": (
                 cls.pprint_styles()