From 689ab844d300e5209d38778dac748b9337919112 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Wed, 25 Oct 2023 23:58:01 +0200
Subject: [PATCH] DOC: Add role for custom informal types like color

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.
---
 doc/sphinxext/custom_roles.py | 15 +++++++++++++++
 lib/matplotlib/widgets.py     |  2 +-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/sphinxext/custom_roles.py b/doc/sphinxext/custom_roles.py
index 3dcecc3df733..8961037ed0f1 100644
--- a/doc/sphinxext/custom_roles.py
+++ b/doc/sphinxext/custom_roles.py
@@ -64,8 +64,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
index cd9716408303..74cac5eec5a1 100644
--- 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.