Skip to content

GH-121970: Extract implementation_detail into a new extension #129663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 6, 2025
Merged

GH-121970: Extract implementation_detail into a new extension #129663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d8573c1
Extract ``implementation_detail`` into a new extension
AA-Turner Feb 4, 2025
23fd315
Merge remote-tracking branch 'upstream/main' into docs/implementation…
AA-Turner Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
'changes',
'glossary_search',
'grammar_snippet',
'implementation_detail',
'lexers',
'misc_news',
'pydoc_topics',
Expand Down
47 changes: 47 additions & 0 deletions Doc/tools/extensions/implementation_detail.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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,
}
26 changes: 0 additions & 26 deletions Doc/tools/extensions/pyspecific.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
15 changes: 9 additions & 6 deletions Doc/tools/templates/dummy.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 %}
Expand All @@ -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 %}
Expand Down
Loading