Skip to content

gh-127833: Docs: Add a grammar-snippet directive & replace productionlist #127835

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
encukou merged 20 commits into from
Feb 5, 2025
Merged

gh-127833: Docs: Add a grammar-snippet directive & replace productionlist #127835

Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
86a0ecc
First version of GrammarSnippetDirective, copied from an earlier branch
encukou Nov 20, 2024
f6ffb21
Add a grammar-snippet directive
blaisep Dec 4, 2024
5cfc701
Remove monkey patch for production list and Add CompatProductionList
blaisep Dec 4, 2024
f0cbed8
Fix ReST grammar
encukou Dec 11, 2024
9139e25
Complete the CompatProductionList class
encukou Dec 11, 2024
b10d78b
Adjust docstrings & move GrammarSnippetDirective class up
encukou Dec 11, 2024
c18a4d3
Merge in the main branch
encukou Dec 11, 2024
a403fb6
Run Ruff
encukou Dec 11, 2024
074c189
Run Ruff again with different flags
encukou Dec 11, 2024
b2fb819
Merge in the main branch
encukou Jan 22, 2025
ea9e2f0
Turn the common function into a class with method; break make_link_to…
encukou Jan 22, 2025
b2205a8
Remove blank line
encukou Jan 22, 2025
829e4f0
Run `ruff format`
encukou Jan 22, 2025
e57a37e
Add forgotten arguments
encukou Jan 22, 2025
fca04c7
Merge in the main branch
encukou Jan 29, 2025
2732143
Use Sphinx's token_xrefs function for formatting the tokens
encukou Jan 29, 2025
ef3c552
Improve the highlight class injection
encukou Jan 29, 2025
c0c8432
Appease Ruff
encukou Jan 29, 2025
e2359b7
Appase Ruff again
encukou Jan 29, 2025
3fcb730
Add type annotations, minor clean-ups
AA-Turner Jan 29, 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
Prev Previous commit
Next Next commit
Run Ruff
  • Loading branch information
@encukou
encukou committed Dec 11, 2024
commit a403fb6219df53d1042895ecc0d01e4f3b3a7406
23 changes: 17 additions & 6 deletions Doc/tools/extensions/grammar_snippet.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ class GrammarSnippetDirective(SphinxDirective):
The content must be preceded by a blank line (like with most ReST
directives).
"""

has_content = True
option_spec = {
'group': directives.unchanged,
Expand Down Expand Up @@ -88,7 +89,7 @@ def make_snippet(directive, options, content):
for match in grammar_re.finditer(line):
# Handle text between matches
if match.start() > last_pos:
literal += nodes.Text(line[last_pos:match.start()])
literal += nodes.Text(line[last_pos : match.start()])
last_pos = match.end()

# Handle matches
Expand All @@ -108,10 +109,16 @@ def make_snippet(directive, options, content):
domain = directive.env.domains['std']
obj_name = f"{group_name}:{name}"
prefix = f'grammar-token-{group_name}'
node_id = make_id(directive.env, directive.state.document, prefix, name)
node_id = make_id(
directive.env, directive.state.document, prefix, name
)
name_node['ids'].append(node_id)
directive.state.document.note_implicit_target(name_node, name_node)
domain.note_object('token', obj_name, node_id, location=name_node)
directive.state.document.note_implicit_target(
name_node, name_node
)
domain.note_object(
'token', obj_name, node_id, location=name_node
)

text_node = nodes.Text(name)
name_node += text_node
Expand All @@ -134,7 +141,8 @@ def make_snippet(directive, options, content):
literal += nodes.Text(line[last_pos:] + '\n')

node = nodes.paragraph(
'', '',
'',
'',
literal,
)

Expand All @@ -149,6 +157,7 @@ class CompatProductionList(SphinxDirective):
It makes existing docs that use the ReST syntax look like grammar-snippet,
as much as possible.
"""

has_content = False
required_arguments = 1
optional_arguments = 0
Expand Down Expand Up @@ -177,5 +186,7 @@ def run(self):

def setup(app):
app.add_directive('grammar-snippet', GrammarSnippetDirective)
app.add_directive_to_domain('std', 'productionlist', CompatProductionList, override=True)
app.add_directive_to_domain(
'std', 'productionlist', CompatProductionList, override=True
)
return {'version': '1.0', 'parallel_read_safe': True}