Debian Codegraph @

Doc/tools/extensions/implementation_detail.py

raw
1 """Support for marking up implementation details."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6
7 from docutils import nodes
8 from sphinx.locale import _ as sphinx_gettext
9 from sphinx.util.docutils import SphinxDirective
10
11 if TYPE_CHECKING:
12 from sphinx.application import Sphinx
13 from sphinx.util.typing import ExtensionMetadata
14
15
16 class ImplementationDetail(SphinxDirective):
17 has_content = True
18 final_argument_whitespace = True
19
20 # This text is copied to templates/dummy.html
21 label_text = sphinx_gettext("CPython implementation detail:")
22
23 def run(self):
24 self.assert_has_content()
25 content_nodes = self.parse_content_to_nodes()
26
27 # insert our prefix at the start of the first paragraph
28 first_node = content_nodes[0]
29 first_node[:0] = [
30 nodes.strong(self.label_text, self.label_text),
31 nodes.Text(" "),
32 ]
33
34 # create a new compound container node
35 cnode = nodes.compound("", *content_nodes, classes=["impl-detail"])
36 self.set_source_info(cnode)
37 return [cnode]
38
39
40 def setup(app: Sphinx) -> ExtensionMetadata:
41 app.add_directive("impl-detail", ImplementationDetail)
42
43 return {
44 "version": "1.0",
45 "parallel_read_safe": True,
46 "parallel_write_safe": True,
47 }