GeezerVison

Copy link

Copy Markdown

Member

willingc reacted with hooray emoji

encukou requested a review from willingc as a code owner December 11, 2024 16:59

encukou requested a review from AA-Turner December 11, 2024 17:11

AA-Turner reviewed Jan 15, 2025

View reviewed changes

AA-Turner reviewed Jan 15, 2025

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

encukou requested a review from hugovk as a code owner January 22, 2025 15:47

AA-Turner reviewed Jan 29, 2025

View reviewed changes

AA-Turner approved these changes Jan 29, 2025

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

encukou deleted the doc-grammar-snippets branch February 5, 2025 15:12

…roductionlist` (pythonGH-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

---------
(cherry picked from commit 58a4357)

Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Blaise Pabon <[email protected]>
Co-authored-by: William Ferreira <[email protected]>
Co-authored-by: bswck <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

…roductionlist` (pythonGH-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

---------
(cherry picked from commit 58a4357)

Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Blaise Pabon <[email protected]>
Co-authored-by: William Ferreira <[email protected]>
Co-authored-by: bswck <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

…roductionlist` (pythonGH-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 <[email protected]>
Co-authored-by: William Ferreira <[email protected]>
Co-authored-by: bswck <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

…roductionlist` (pythonGH-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 <[email protected]>
Co-authored-by: William Ferreira <[email protected]>
Co-authored-by: bswck <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

In gh-138418, `!` was added to links to rules that don't exist in
the docs, in order to silence broken link warnings.
However, productionlist doesn't parse the `!`, which ends up in
the rendered documentation. (It's possible that gh-127835 broke
the `!` support.)

Replace the names with ones that appear in docs:

- `star_named_expression` in the grammar corresponds to
  `flexible_expression` in the docs
- `star_named_expressions` in the grammar corresponds to
  `flexible_expression_list` in the docs
- `named_expression` in the grammar corresponds to
  `assignment_expression` in the docs

Having two sets of names isn't great of course. Consolidating them
is tracked in (subissues of) gh-127833.

…49836)

Link to existing rules in compound_stmts.rst (GH-149811)

In gh-138418, `!` was added to links to rules that don't exist in
the docs, in order to silence broken link warnings.
However, productionlist doesn't parse the `!`, which ends up in
the rendered documentation. (It's possible that gh-127835 broke
the `!` support.)

Replace the names with ones that appear in docs:

- `star_named_expression` in the grammar corresponds to
  `flexible_expression` in the docs
- `star_named_expressions` in the grammar corresponds to
  `flexible_expression_list` in the docs
- `named_expression` in the grammar corresponds to
  `assignment_expression` in the docs

Having two sets of names isn't great of course. Consolidating them
is tracked in (subissues of) gh-127833.
(cherry picked from commit c375292)

Co-authored-by: Petr Viktorin <[email protected]>

…49837)

Link to existing rules in compound_stmts.rst (GH-149811)

In gh-138418, `!` was added to links to rules that don't exist in
the docs, in order to silence broken link warnings.
However, productionlist doesn't parse the `!`, which ends up in
the rendered documentation. (It's possible that gh-127835 broke
the `!` support.)

Replace the names with ones that appear in docs:

- `star_named_expression` in the grammar corresponds to
  `flexible_expression` in the docs
- `star_named_expressions` in the grammar corresponds to
  `flexible_expression_list` in the docs
- `named_expression` in the grammar corresponds to
  `assignment_expression` in the docs

Having two sets of names isn't great of course. Consolidating them
is tracked in (subissues of) gh-127833.
(cherry picked from commit c375292)

Co-authored-by: Petr Viktorin <[email protected]>

…49838)

Link to existing rules in compound_stmts.rst (GH-149811)

In gh-138418, `!` was added to links to rules that don't exist in
the docs, in order to silence broken link warnings.
However, productionlist doesn't parse the `!`, which ends up in
the rendered documentation. (It's possible that gh-127835 broke
the `!` support.)

Replace the names with ones that appear in docs:

- `star_named_expression` in the grammar corresponds to
  `flexible_expression` in the docs
- `star_named_expressions` in the grammar corresponds to
  `flexible_expression_list` in the docs
- `named_expression` in the grammar corresponds to
  `assignment_expression` in the docs

Having two sets of names isn't great of course. Consolidating them
is tracked in (subissues of) gh-127833.
(cherry picked from commit c375292)

Co-authored-by: Petr Viktorin <[email protected]>