Fix links to rcParams sample matplotlibrc

The anchor ID was changed, but as this was entered manually, it did not
break the build.

Instead, insert a pending cross-reference so that Sphinx will resolve it
and warn if it breaks.

The output changes minimally from `external` to `internal` class, and
also gains `std std-ref` classes due to it being a standard reference.

Author: QuLogic

doc/sphinxext/custom_roles.py

@@ -1,21 +1,57 @@
+from urllib.parse import urlsplit, urlunsplit
+
 from docutils import nodes
-from os.path import sep
+
 from matplotlib import rcParamsDefault
 
 
-def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    rendered = nodes.Text(f'rcParams["{text}"]')
+class QueryReference(nodes.Inline, nodes.TextElement):
+    """
+    Wraps a reference or pending reference to add a query string.
+
+    The query string is generated from the attributes added to this node.
+
+    Also equivalent to a `~docutils.nodes.literal` node.
+    """
+
+    def to_query_string(self):
+        """Generate query string from node attributes."""
+        return '&'.join(f'{name}={value}' for name, value in self.attlist())
+
+
+def visit_query_reference_node(self, node):
+    """
+    Resolve *node* into query strings on its ``reference`` children.
 
-    source = inliner.document.attributes['source'].replace(sep, '/')
-    rel_source = source.split('/doc/', 1)[1]
+    Then act as if this is a `~docutils.nodes.literal`.
+    """
+    query = node.to_query_string()
+    for refnode in node.findall(nodes.reference):
+        uri = urlsplit(refnode['refuri'])._replace(query=query)
+        refnode['refuri'] = urlunsplit(uri)
 
-    levels = rel_source.count('/')
-    refuri = ('../' * levels +
-              'tutorials/introductory/customizing.html' +
-              f"?highlight={text}#a-sample-matplotlibrc-file")
+    self.visit_literal(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=[]):
+    # Generate a pending cross-reference so that Sphinx will ensure this link
+    # isn't broken at some point in the future.
+    title = f'rcParam["{text}"]'
+    target = 'matplotlibrc-sample'
+    ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
+                                              'ref', lineno)
+
+    qr = QueryReference(rawtext, highlight=text)
+    qr += ref_nodes
+    node_list = [qr]
 
-    ref = nodes.reference(rawtext, rendered, refuri=refuri)
-    node_list = [nodes.literal('', '', ref)]
     # The default backend would be printed as "agg", but that's not correct (as
     # the default is actually determined by fallback).
     if text in rcParamsDefault and text != "backend":
@@ -24,9 +60,16 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
             nodes.literal('', repr(rcParamsDefault[text])),
             nodes.Text(')'),
             ])
-    return node_list, []
+
+    return node_list, messages
 
 
 def setup(app):
     app.add_role("rc", rcparam_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),
+    )
     return {"parallel_read_safe": True, "parallel_write_safe": True}