Skip to content

gh-127833: Fix grammar snippet formatting for help() output #129692

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

Closed
encukou wants to merge 6 commits into from
+326 −307
Closed

gh-127833: Fix grammar snippet formatting for help() output #129692

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
af3ce4f
Fix grammar snippet formatting for help() output
encukou Feb 5, 2025
1af8b90
Commit the generated pydoc_data changes
encukou Feb 5, 2025
c495762
Merge branch 'main' into doc-grammar-snippets
hugovk Feb 6, 2025
1969945
Fix annotation and run `ruff check Doc/tools/ --fix`
encukou Feb 12, 2025
69482f2
Merge in the main branch
encukou Feb 12, 2025
f04e70a
Remove space from autogenerated file
encukou Feb 12, 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
11 changes: 10 additions & 1 deletion Doc/tools/extensions/grammar_snippet.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ def __init__(
self['classes'].append('sx')


class grammar_snippet(nodes.literal_block): # noqa: N801 (snake_case)
"""Node for a grammar snippet"""

grammar_snippet_content: Sequence[str]


class GrammarSnippetBase(SphinxDirective):
"""Common functionality for GrammarSnippetDirective & CompatProductionList."""

Expand All @@ -58,11 +64,14 @@ def make_grammar_snippet(
# To get around this, we set it to this non-empty string:
rawsource = 'You should not see this.'

literal = nodes.literal_block(
literal = grammar_snippet(
rawsource,
'',
classes=['highlight'],
)
# Save a copy of the "input" content. For plain text, we want to
# output this verbatim.
literal.grammar_snippet_content = list(content)

grammar_re = re.compile(
r"""
Expand Down
11 changes: 10 additions & 1 deletion Doc/tools/extensions/pydoc_topics.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
from sphinx.util.display import status_iterator
from sphinx.util.docutils import new_document
from sphinx.writers.text import TextTranslator
from docutils import nodes
Comment thread
encukou marked this conversation as resolved.
Outdated

if TYPE_CHECKING:
from collections.abc import Sequence, Set
Expand Down Expand Up @@ -102,6 +103,14 @@
"yield",
})

class PydocTextTranslator(TextTranslator):
Comment thread
encukou marked this conversation as resolved.
def visit_grammar_snippet(self, node: Element) -> None:
Comment thread
encukou marked this conversation as resolved.
Outdated
"""For grammar snippets, return the "input" as is."""
self.new_state()
self.add_text(self.nl.join(node.grammar_snippet_content))
self.end_state(wrap=False)
raise nodes.SkipNode


class PydocTopicsBuilder(TextBuilder):
name = "pydoc-topics"
Expand Down Expand Up @@ -141,7 +150,7 @@ def write_documents(self, _docnames: Set[str]) -> None:
for topic_label, label_id in label_ids:
document = new_document("<section node>")
document.append(doc_ids[label_id])
visitor = TextTranslator(document, builder=self)
visitor = PydocTextTranslator(document, builder=self)
document.walkabout(visitor)
self.topics[topic_label] = visitor.body

Expand Down
Loading