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
+226 −2
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
Use Sphinx's token_xrefs function for formatting the tokens
  • Loading branch information
@encukou
encukou committed Jan 29, 2025
commit 27321430b6affde9140e71f2f18ce9fa1a831b17
22 changes: 8 additions & 14 deletions Doc/tools/extensions/grammar_snippet.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from sphinx import addnodes
from sphinx.util.docutils import SphinxDirective
from sphinx.util.nodes import make_id
from sphinx.domains.std import token_xrefs


class GrammarSnippetBase(SphinxDirective):
Expand Down Expand Up @@ -36,11 +37,11 @@ def make_grammar_snippet(self, options, content):
)

grammar_re = re.compile(
"""
r"""
(?P<rule_name>^[a-zA-Z0-9_]+) # identifier at start of line
(?=:) # ... followed by a colon
|
[`](?P<rule_ref>[a-zA-Z0-9_]+)[`] # identifier in backquotes
(?P<rule_ref>`[^\s`]+`) # identifier in backquotes
|
(?P<single_quoted>'[^']*') # string in 'quotes'
|
Expand All @@ -65,16 +66,9 @@ def make_grammar_snippet(self, options, content):
}
match groupdict:
case {'rule_name': name}:
literal += self.make_link_to_token(group_name, name)
case {'rule_ref': name}:
ref_node = addnodes.pending_xref(
name,
reftype="token",
refdomain="std",
reftarget=f"{group_name}:{name}",
)
ref_node += nodes.Text(name)
literal += ref_node
literal += self.make_link_target_for_token(group_name, name)
case {'rule_ref': ref_text}:
literal += token_xrefs(ref_text, group_name)
case {'single_quoted': name} | {'double_quoted': name}:
string_node = nodes.inline(classes=['nb'])
string_node += nodes.Text(name)
Expand All @@ -91,8 +85,8 @@ def make_grammar_snippet(self, options, content):

return [node]

def make_link_to_token(self, group_name, name):
"""Return a literal node that links to the given grammar token"""
def make_link_target_for_token(self, group_name, name):
"""Return a literal node which is a link target for the given token"""
name_node = addnodes.literal_strong()

# Cargo-culted magic to make `name_node` a link target
Expand Down