]> git.ipfire.org Git - thirdparty/Python/cpython.git/commit
gh-127833: Docs: Add a `grammar-snippet` directive & replace `productionlist` (GH...
authorPetr Viktorin <encukou@gmail.com>
Wed, 5 Feb 2025 15:12:23 +0000 (16:12 +0100)
committerGitHub <noreply@github.com>
Wed, 5 Feb 2025 15:12:23 +0000 (16:12 +0100)
commit58a4357e29a15135e6fd99f320c60f8ea0472d27
tree6147d1f90a9ae01253fb8d7587d7b43ba1f2f7b2
parente5c3b7e34974dcd6d7f6a1a50030bf7fbce38e74
gh-127833: Docs: Add a `grammar-snippet` directive & replace `productionlist` (GH-127835)

As a first step toward aligning the grammar documentation with Python's actual
grammar, this overrides the ReST `productionlist` directive to:
- use `:` instead of the `::=` symbol
- add syntax highlighting for strings (using a Pygments highlighting 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
(file:///home/encukou/dev/cpython/Doc/build/html/reference/grammar.html).

The new directive is applied to two simple rules in toplevel_components.rst

---------

Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: William Ferreira <wqferr@gmail.com>
Co-authored-by: bswck <bartoszpiotrslawecki@gmail.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Doc/conf.py
Doc/reference/toplevel_components.rst
Doc/tools/extensions/grammar_snippet.py [new file with mode: 0644]