Proof of concept for adding kwdoc content to properties using a decorator

timhoffm · oscargus · commit d47f98661d99 · 2023-04-07T15:19:03.000+02:00
diff --git a/lib/matplotlib/_docstring.py b/lib/matplotlib/_docstring.py
@@ -3,6 +3,34 @@
 from . import _api
 
 
+def kwarg_doc(text):
+    """
+    Decorator for artist property setters, defining the documentation used when
+    artist properties are passed through as keyword arguments.
+
+    We generate lists of kwargs by inspecting the properties on a class, and then refer
+    to them in the documentation as, for example, ``%(Text:kwdoc)s``, which is used in
+    the `**kwargs` section in `.Axes.text`.  However, sometimes the setter function
+    parameter description is not what we want in this generated list, or we cannot pick
+    up the correct description.
+
+    This method adds the given text to a private variable ``_kwarg_doc`` on the class.
+    It will be used for generating the kwdoc list for artists instead of the parameter
+    docs.
+
+    The text should contain the supported types as well as the default value
+    if applicable, e.g.:
+
+        @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
+        def set_usetex(self, usetex):
+
+    """
+    def decorator(func):
+        func._kwarg_doc = text
+        return func
+    return decorator
+
+
 class Substitution:
     """
     A decorator that performs %-substitution on an object's docstring.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1479,6 +1479,9 @@ def get_valid_values(self, attr):
             raise AttributeError(f'{self.o} has no function {name}')
         func = getattr(self.o, name)
 
+        if hasattr(func, '_kwarg_doc'):
+            return func._kwarg_doc
+
         docstring = inspect.getdoc(func)
         if docstring is None:
             return 'unknown'
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -1282,6 +1282,7 @@ def set_fontproperties(self, fp):
         self._fontproperties = FontProperties._from_any(fp).copy()
         self.stale = True
 
+    @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
     def set_usetex(self, usetex):
         """
         Parameters
