DOC: Add role for custom informal types like color

timhoffm · timhoffm · commit cfd284f4f232 · 2023-10-25T23:58:01.000+02:00
The role is intended to be used for type references in docstrings like ``` Parameters ---------- color : :mpltype:`color` ``` It is easily extendable to other types. The naming `mpltype` was a quick choice. I'm open to better names. This PR contains one example usage in `widgets.Button` so that one can see the effect in the built docs. Systematic application throughout the codebase should be deferred to a separate PR. Closes #24859. Formalizes #27164.
diff --git a/doc/sphinxext/custom_roles.py b/doc/sphinxext/custom_roles.py
@@ -1,6 +1,7 @@
 from urllib.parse import urlsplit, urlunsplit
 
 from docutils import nodes
+from sphinx.util.nodes import make_refnode
 
 from matplotlib import rcParamsDefault
 
@@ -64,8 +65,23 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     return node_list, messages
 
 
+def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    mpltype = text
+    type_to_link_target = {
+        'color': 'colors_def',
+    }
+    if mpltype not in type_to_link_target:
+        raise ValueError(f"Unknown mpltype: {mpltype!r}")
+
+    ref_nodes, messages = inliner.interpreted(
+        mpltype, f'{mpltype} <{type_to_link_target[mpltype]}>', 'ref', lineno)
+    node_list = [ref_nodes]
+    return node_list, messages
+
+
 def setup(app):
     app.add_role("rc", rcparam_role)
+    app.add_role("mpltype", mpltype_role)
     app.add_node(
         QueryReference,
         html=(visit_query_reference_node, depart_query_reference_node),
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -191,7 +191,7 @@ def __init__(self, ax, label, image=None,
         image : array-like or PIL Image
             The image to place in the button, if not *None*.  The parameter is
             directly forwarded to `~.axes.Axes.imshow`.
-        color : color
+        color : :mpltype:`color`
             The color of the button when not activated.
         hovercolor : color
             The color of the button when the mouse is over it.
