Promote mpltype Sphinx role to a public extension

QuLogic · QuLogic · commit 5fee0fa97e88 · 2024-05-23T16:02:41.000-04:00
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.
diff --git a/doc/conf.py b/doc/conf.py
@@ -116,9 +116,9 @@ def _parse_skip_subdirs_file():
     'sphinx_gallery.gen_gallery',
     'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.plot_directive',
+    'matplotlib.sphinxext.roles',
     'matplotlib.sphinxext.figmpl_directive',
     'sphinxcontrib.inkscapeconverter',
-    'sphinxext.custom_roles',
     'sphinxext.github',
     'sphinxext.math_symbol_table',
     'sphinxext.missing_references',
diff --git a/lib/matplotlib/sphinxext/meson.build b/lib/matplotlib/sphinxext/meson.build
@@ -3,6 +3,7 @@ python_sources = [
   'figmpl_directive.py',
   'mathmpl.py',
   'plot_directive.py',
+  'roles.py',
 ]
 
 typing_sources = [
diff --git a/lib/matplotlib/sphinxext/roles.py b/lib/matplotlib/sphinxext/roles.py
@@ -5,7 +5,7 @@
 from matplotlib import rcParamsDefault
 
 
-class QueryReference(nodes.Inline, nodes.TextElement):
+class _QueryReference(nodes.Inline, nodes.TextElement):
     """
     Wraps a reference or pending reference to add a query string.
 
@@ -19,7 +19,7 @@ def to_query_string(self):
         return '&'.join(f'{name}={value}' for name, value in self.attlist())
 
 
-def visit_query_reference_node(self, node):
+def _visit_query_reference_node(self, node):
     """
     Resolve *node* into query strings on its ``reference`` children.
 
@@ -33,22 +33,22 @@ def visit_query_reference_node(self, node):
     self.visit_literal(node)
 
 
-def depart_query_reference_node(self, node):
+def _depart_query_reference_node(self, node):
     """
     Act as if this is a `~docutils.nodes.literal`.
     """
     self.depart_literal(node)
 
 
-def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def _rcparam_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     # Generate a pending cross-reference so that Sphinx will ensure this link
     # isn't broken at some point in the future.
     title = f'rcParams["{text}"]'
     target = 'matplotlibrc-sample'
     ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
                                               'ref', lineno)
 
-    qr = QueryReference(rawtext, highlight=text)
+    qr = _QueryReference(rawtext, highlight=text)
     qr += ref_nodes
     node_list = [qr]
 
@@ -64,7 +64,7 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     return node_list, messages
 
 
-def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     mpltype = text
     type_to_link_target = {
         'color': 'colors_def',
@@ -78,12 +78,12 @@ def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
 
 def setup(app):
-    app.add_role("rc", rcparam_role)
-    app.add_role("mpltype", mpltype_role)
+    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),
-        latex=(visit_query_reference_node, depart_query_reference_node),
-        text=(visit_query_reference_node, depart_query_reference_node),
+        _QueryReference,
+        html=(_visit_query_reference_node, _depart_query_reference_node),
+        latex=(_visit_query_reference_node, _depart_query_reference_node),
+        text=(_visit_query_reference_node, _depart_query_reference_node),
     )
     return {"parallel_read_safe": True, "parallel_write_safe": True}
diff --git a/pyproject.toml b/pyproject.toml
@@ -283,11 +283,11 @@ ignore_directives = [
     "include"
 ]
 ignore_roles = [
-    # sphinxext.custom_roles
-    "rc",
     # matplotlib.sphinxext.mathmpl
     "mathmpl",
     "math-stix",
+    # matplotlib.sphinxext.roles
+    "rc",
     # sphinxext.github
     "ghissue",
     "ghpull",

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@ python_sources = [`
`3`	`3`	`'figmpl_directive.py',`
`4`	`4`	`'mathmpl.py',`
`5`	`5`	`'plot_directive.py',`
	`6`	`+ 'roles.py',`
`6`	`7`	`]`
`7`	`8`
`8`	`9`	`typing_sources = [`