diff --git a/Doc/conf.py b/Doc/conf.py index a4e0c628649018..56594f32c6d02d 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -28,6 +28,7 @@ 'changes', 'glossary_search', 'grammar_snippet', + 'implementation_detail', 'lexers', 'misc_news', 'pydoc_topics', diff --git a/Doc/tools/extensions/implementation_detail.py b/Doc/tools/extensions/implementation_detail.py new file mode 100644 index 00000000000000..fce8375e40d565 --- /dev/null +++ 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 index 57cf80a7e77324..c12d169c0cfe7a 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -65,31 +65,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) @@ -219,7 +194,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_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature) app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command) app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event) diff --git a/Doc/tools/templates/dummy.html b/Doc/tools/templates/dummy.html index 4f0f6f91436a87..0fdbe2a58017ff 100644 --- 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 %}