NotificationsYou must be signed in to change notification settings
Fork32k
Star67.3k

[3.12] gh-127833: Docs: Add a`grammar-snippet` directive & replace`productionlist` (GH-127835)#129690

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.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Jump to bottom

Closed

miss-islington wants to merge1 commit intopython:3.12frommiss-islington:backport-58a4357-3.12

Closed

[3.12] gh-127833: Docs: Add a`grammar-snippet` directive & replace`productionlist` (GH-127835)#129690

miss-islington wants to merge1 commit intopython:3.12frommiss-islington:backport-58a4357-3.12

Conversation

Copy link

Contributor

miss-islington commentedFeb 5, 2025•
edited by github-actionsbot
Loading

As a first step toward aligning the grammar documentation with Python's actual
grammar, this overrides the ReSTproductionlist 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

(cherry picked from commit58a4357)

Co-authored-by: Petr Viktorinencukou@gmail.com
Co-authored-by: Blaise Pabonblaise@gmail.com
Co-authored-by: William Ferreirawqferr@gmail.com
Co-authored-by: bswckbartoszpiotrslawecki@gmail.com
Co-authored-by: Adam Turner9087854+aa-turner@users.noreply.github.com

Issue:Align the grammar documentation with Python's actual grammar #127833

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

pythongh-127833: Docs: Add agrammar-snippetdirective & replace `p…

14991a4

…roductionlist` (pythonGH-127835)As a first step toward aligning the grammar documentation with Python's actualgrammar, 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 reachesinto some Sphinx internals; I don't see a better way to do exactly whatSphinx does.)This also adds a new directive, `grammar-snippet`, which formats the snippetalmost exactly like what's in the source, modulo syntax highlighting andkeeping 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---------(cherry picked from commit58a4357)Co-authored-by: Petr Viktorin <encukou@gmail.com>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>