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.
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy