Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 8e95749

Browse filesBrowse files
committed
Promote mpltype Sphinx role to a public extension
When projects derive from our types, but don't override all the docstrings, they may want to use these extensions so that their docs build.
1 parent a833d99 commit 8e95749
Copy full SHA for 8e95749

File tree

5 files changed

+33
-16
lines changed
Filter options

5 files changed

+33
-16
lines changed
+14Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Documentation-specific custom Sphinx roles are now semi-public
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
For third-party packages that derive types from Matplotlib, our use of custom roles may
5+
prevent Sphinx from building their docs. These custom Sphinx roles are now public solely
6+
for the purposes of use within projects that derive from Matplotlib types, and may be
7+
added to Sphinx via ``conf.py``::
8+
9+
extensions = [
10+
'matplotlib.sphinxext.roles',
11+
# Other extensions.
12+
]
13+
14+
Any other use of these roles is not supported.

‎doc/conf.py

Copy file name to clipboardExpand all lines: doc/conf.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,9 @@ def _parse_skip_subdirs_file():
116116
'sphinx_gallery.gen_gallery',
117117
'matplotlib.sphinxext.mathmpl',
118118
'matplotlib.sphinxext.plot_directive',
119+
'matplotlib.sphinxext.roles',
119120
'matplotlib.sphinxext.figmpl_directive',
120121
'sphinxcontrib.inkscapeconverter',
121-
'sphinxext.custom_roles',
122122
'sphinxext.github',
123123
'sphinxext.math_symbol_table',
124124
'sphinxext.missing_references',

‎lib/matplotlib/sphinxext/meson.build

Copy file name to clipboardExpand all lines: lib/matplotlib/sphinxext/meson.build
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ python_sources = [
33
'figmpl_directive.py',
44
'mathmpl.py',
55
'plot_directive.py',
6+
'roles.py',
67
]
78

89
typing_sources = [

‎doc/sphinxext/custom_roles.py renamed to ‎lib/matplotlib/sphinxext/roles.py

Copy file name to clipboardExpand all lines: lib/matplotlib/sphinxext/roles.py
+15-13Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@
22

33
from docutils import nodes
44

5+
import matplotlib
56
from matplotlib import rcParamsDefault
67

78

8-
class QueryReference(nodes.Inline, nodes.TextElement):
9+
class _QueryReference(nodes.Inline, nodes.TextElement):
910
"""
1011
Wraps a reference or pending reference to add a query string.
1112
@@ -19,7 +20,7 @@ def to_query_string(self):
1920
return '&'.join(f'{name}={value}' for name, value in self.attlist())
2021

2122

22-
def visit_query_reference_node(self, node):
23+
def _visit_query_reference_node(self, node):
2324
"""
2425
Resolve *node* into query strings on its ``reference`` children.
2526
@@ -33,22 +34,22 @@ def visit_query_reference_node(self, node):
3334
self.visit_literal(node)
3435

3536

36-
def depart_query_reference_node(self, node):
37+
def _depart_query_reference_node(self, node):
3738
"""
3839
Act as if this is a `~docutils.nodes.literal`.
3940
"""
4041
self.depart_literal(node)
4142

4243

43-
def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
44+
def _rcparam_role(name, rawtext, text, lineno, inliner, options=None, content=None):
4445
# Generate a pending cross-reference so that Sphinx will ensure this link
4546
# isn't broken at some point in the future.
4647
title = f'rcParams["{text}"]'
4748
target = 'matplotlibrc-sample'
4849
ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
4950
'ref', lineno)
5051

51-
qr = QueryReference(rawtext, highlight=text)
52+
qr = _QueryReference(rawtext, highlight=text)
5253
qr += ref_nodes
5354
node_list = [qr]
5455

@@ -64,7 +65,7 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
6465
return node_list, messages
6566

6667

67-
def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
68+
def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=None):
6869
mpltype = text
6970
type_to_link_target = {
7071
'color': 'colors_def',
@@ -78,12 +79,13 @@ def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
7879

7980

8081
def setup(app):
81-
app.add_role("rc", rcparam_role)
82-
app.add_role("mpltype", mpltype_role)
82+
app.add_role("rc", _rcparam_role)
83+
app.add_role("mpltype", _mpltype_role)
8384
app.add_node(
84-
QueryReference,
85-
html=(visit_query_reference_node, depart_query_reference_node),
86-
latex=(visit_query_reference_node, depart_query_reference_node),
87-
text=(visit_query_reference_node, depart_query_reference_node),
85+
_QueryReference,
86+
html=(_visit_query_reference_node, _depart_query_reference_node),
87+
latex=(_visit_query_reference_node, _depart_query_reference_node),
88+
text=(_visit_query_reference_node, _depart_query_reference_node),
8889
)
89-
return {"parallel_read_safe": True, "parallel_write_safe": True}
90+
return {"version": matplotlib.__version__,
91+
"parallel_read_safe": True, "parallel_write_safe": True}

‎pyproject.toml

Copy file name to clipboardExpand all lines: pyproject.toml
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,11 +283,11 @@ ignore_directives = [
283283
"include"
284284
]
285285
ignore_roles = [
286-
# sphinxext.custom_roles
287-
"rc",
288286
# matplotlib.sphinxext.mathmpl
289287
"mathmpl",
290288
"math-stix",
289+
# matplotlib.sphinxext.roles
290+
"rc",
291291
# sphinxext.github
292292
"ghissue",
293293
"ghpull",

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.