Don't remove substitution_reference nodes (fix #7953)

SubstitutionDefinitionsRemover is now a SphinxPostTransform, only
applied in the Sphinx builder, as was originally the case (see #4827).

sphinx/builders/latex/transforms.py

@@ -13,6 +13,7 @@ from typing import cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
+from docutils.transforms.references import Substitutions
 
 from sphinx import addnodes
 from sphinx.application import Sphinx
@@ -38,6 +39,18 @@ class FootnoteDocnameUpdater(SphinxTransform):
             node['docname'] = self.env.docname
 
 
+class SubstitutionDefinitionsRemover(SphinxPostTransform):
+    """Remove ``substitution_definition node from doctrees."""
+
+    # should be invoked after Substitutions process
+    default_priority = Substitutions.default_priority + 1
+    builders = ('latex',)
+
+    def apply(self, **kwargs: Any) -> None:
+        for node in self.document.traverse(nodes.substitution_definition):
+            node.parent.remove(node)
+
+
 class ShowUrlsTransform(SphinxPostTransform):
     """Expand references to inline text or footnotes.
 
@@ -602,6 +615,7 @@ class IndexInSectionTitleTransform(SphinxTransform):
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_transform(FootnoteDocnameUpdater)
+    app.add_post_transform(SubstitutionDefinitionsRemover)
     app.add_post_transform(BibliographyTransform)
     app.add_post_transform(CitationReferenceTransform)
     app.add_post_transform(DocumentTargetTransform)

sphinx/transforms/references.py

@@ -10,8 +10,7 @@
 
 from typing import Any, Dict
 
-from docutils import nodes
-from docutils.transforms.references import DanglingReferences, Substitutions
+from docutils.transforms.references import DanglingReferences
 
 from sphinx.transforms import SphinxTransform
 
@@ -20,17 +19,6 @@ if False:
     from sphinx.application import Sphinx
 
 
-class SubstitutionDefinitionsRemover(SphinxTransform):
-    """Remove ``substitution_definition node from doctrees."""
-
-    # should be invoked after Substitutions process
-    default_priority = Substitutions.default_priority + 1
-
-    def apply(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(nodes.substitution_definition):
-            node.parent.remove(node)
-
-
 class SphinxDanglingReferences(DanglingReferences):
     """DanglingReferences transform which does not output info messages."""
 
@@ -56,7 +44,6 @@ class SphinxDomains(SphinxTransform):
 
 
 def setup(app: "Sphinx") -> Dict[str, Any]:
-    app.add_transform(SubstitutionDefinitionsRemover)
     app.add_transform(SphinxDanglingReferences)
     app.add_transform(SphinxDomains)
 

sphinx/writers/texinfo.py

@@ -1242,6 +1242,15 @@ class TexinfoTranslator(SphinxTranslator):
     def depart_legend(self, node: Element) -> None:
         pass
 
+    def visit_substitution_reference(self, node: Element) -> None:
+        pass
+
+    def depart_substitution_reference(self, node: Element) -> None:
+        pass
+
+    def visit_substitution_definition(self, node: Element) -> None:
+        raise nodes.SkipNode
+
     def visit_system_message(self, node: Element) -> None:
         self.body.append('\n@verbatim\n'
                          '<SYSTEM MESSAGE: %s>\n'

sphinx/writers/text.py

@@ -1013,6 +1013,9 @@ class TextTranslator(SphinxTranslator):
     def visit_toctree(self, node: Element) -> None:
         raise nodes.SkipNode
 
+    def visit_substitution_definition(self, node: Element) -> None:
+        raise nodes.SkipNode
+
     def visit_pending_xref(self, node: Element) -> None:
         pass