| 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 |
} |