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.

doc/api/next_api_changes/development/28289-ES.rst

@@ -0,0 +1,14 @@
+Documentation-specific custom Sphinx roles are now semi-public
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For third-party packages that derive types from Matplotlib, our use of custom roles may
+prevent Sphinx from building their docs. These custom Sphinx roles are now public solely
+for the purposes of use within projects that derive from Matplotlib types, and may be
+added to Sphinx via ``conf.py``::
+
+    extensions = [
+        'matplotlib.sphinxext.roles',
+        # Other extensions.
+    ]
+
+Any other use of these roles is not supported.

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',

lib/matplotlib/sphinxext/meson.build

@@ -3,6 +3,7 @@ python_sources = [
   'figmpl_directive.py',
   'mathmpl.py',
   'plot_directive.py',
+  'roles.py',
 ]
 
 typing_sources = [

doc/sphinxext/custom_roles.py → lib/matplotlib/sphinxext/roles.py

@@ -2,10 +2,11 @@
 
 from docutils import nodes
 
+import matplotlib
 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 +20,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 +34,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 +65,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 +79,13 @@ 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}
+    return {"version": matplotlib.__version__,
+            "parallel_read_safe": True, "parallel_write_safe": True}

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",