[3.12] GH-121970: Extract implementation_detail into a new extension (GH-129663) (#129740)

AA-Turner · web-flow · commit 3dc5bcee67e7 · 2025-02-06T17:33:13.000Z
(cherry picked from commit 4d56c40)
diff --git a/Doc/conf.py b/Doc/conf.py
@@ -27,6 +27,7 @@
     'c_annotations',
     'changes',
     'glossary_search',
+    'implementation_detail',
     'lexers',
     'misc_news',
     'pyspecific',
diff --git a/Doc/tools/extensions/implementation_detail.py b/Doc/tools/extensions/implementation_detail.py
@@ -0,0 +1,47 @@
+"""Support for marking up implementation details."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from sphinx.locale import _ as sphinx_gettext
+from sphinx.util.docutils import SphinxDirective
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+class ImplementationDetail(SphinxDirective):
+    has_content = True
+    final_argument_whitespace = True
+
+    # This text is copied to templates/dummy.html
+    label_text = sphinx_gettext("CPython implementation detail:")
+
+    def run(self):
+        self.assert_has_content()
+        content_nodes = self.parse_content_to_nodes()
+
+        # insert our prefix at the start of the first paragraph
+        first_node = content_nodes[0]
+        first_node[:0] = [
+            nodes.strong(self.label_text, self.label_text),
+            nodes.Text(" "),
+        ]
+
+        # create a new compound container node
+        cnode = nodes.compound("", *content_nodes, classes=["impl-detail"])
+        self.set_source_info(cnode)
+        return [cnode]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_directive("impl-detail", ImplementationDetail)
+
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
@@ -71,31 +71,6 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     return [refnode], []
 
 
-# Support for marking up implementation details
-
-class ImplementationDetail(SphinxDirective):
-
-    has_content = True
-    final_argument_whitespace = True
-
-    # This text is copied to templates/dummy.html
-    label_text = sphinx_gettext('CPython implementation detail:')
-
-    def run(self):
-        self.assert_has_content()
-        pnode = nodes.compound(classes=['impl-detail'])
-        content = self.content
-        add_text = nodes.strong(self.label_text, self.label_text)
-        self.state.nested_parse(content, self.content_offset, pnode)
-        content = nodes.inline(pnode[0].rawsource, translatable=True)
-        content.source = pnode[0].source
-        content.line = pnode[0].line
-        content += pnode[0].children
-        pnode[0].replace_self(nodes.paragraph(
-            '', '', add_text, nodes.Text(' '), content, translatable=False))
-        return [pnode]
-
-
 class PyCoroutineMixin(object):
     def handle_signature(self, sig, signode):
         ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
@@ -288,7 +263,6 @@ def patch_pairindextypes(app, _env) -> None:
 def setup(app):
     app.add_role('issue', issue_role)
     app.add_role('gh', gh_issue_role)
-    app.add_directive('impl-detail', ImplementationDetail)
     app.add_builder(PydocTopicsBuilder)
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
     app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
diff --git a/Doc/tools/templates/dummy.html b/Doc/tools/templates/dummy.html
@@ -1,12 +1,6 @@
 This file is not an actual template, but used to add some
 texts in extensions to sphinx.pot file.
 
-In extensions/pyspecific.py:
-
-{% trans %}CPython implementation detail:{% endtrans %}
-{% trans %}Deprecated since version {deprecated}, will be removed in version {removed}{% endtrans %}
-{% trans %}Deprecated since version {deprecated}, removed in version {removed}{% endtrans %}
-
 In extensions/availability.py:
 
 {% trans %}Availability{% endtrans %}
@@ -27,6 +21,15 @@
 {% trans %}Return value: New reference.{% endtrans %}
 {% trans %}Return value: Borrowed reference.{% endtrans %}
 
+In extensions/implementation_detail.py:
+
+{% trans %}CPython implementation detail:{% endtrans %}
+
+In extensions/changes.py:
+
+{% trans %}Deprecated since version {deprecated}, will be removed in version {removed}{% endtrans %}
+{% trans %}Deprecated since version {deprecated}, removed in version {removed}{% endtrans %}
+
 In docsbuild-scripts, when rewriting indexsidebar.html with actual versions:
 
 {% trans %}in development{% endtrans %}
