Skip to content

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

Merged
encukou merged 20 commits intopython:mainfrom
encukou:doc-grammar-snippets
Feb 5, 2025
Merged

gh-127833: Docs: Add a grammar-snippet directive & replace productionlist#127835
encukou merged 20 commits intopython:mainfrom
encukou:doc-grammar-snippets

Conversation

@encukou
Copy link
Copy Markdown
Member

@encukou encukou commented Dec 11, 2024

As a first step to what's proposed in the issue, this overrides the ReST productionlist directive to:

  • use : instead of the ::= symbol
  • add syntax highlighting for strings (the implementation is preliminary; I intend to later add a proper class to the theme instead of borrowing a Pygments class.)

All links and link targets should be preserved. (Unfortunately, this reaches into some Sphinx internals; I don't see a better way to do exactly what Sphinx does.)

This also adds a new directive, grammar-snippet, which formats the snippet almost exactly like what's in the source, modulo syntax highlighting and keeping the backtick character to mark links to other rules.
This will allow formatting the snippets as in the grammar file (most importantly: to remove the the indentation that Sphinx adds to align the text).

I'd appreciate if a Sphinx expert could take a look to see if there's a better way to do something :) cc @AA-Turner


📚 Documentation preview 📚: https://cpython-previews--127835.org.readthedocs.build/

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants