gh-127833: Docs: Add a `grammar-snippet` directive & replace `productionlist` by encukou · Pull Request #127835 · python/cpython
and others added 6 commits
Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: William Ferreira <wqferr@gmail.com>
to conserve the productionlist usage in the docs.
Co-Authored-By: bswck <bartoszpiotrslawecki@gmail.com>
- Add a module docstring - Use the snake_case convention for node classes - Make :group: a required option - declare parallel_write_safe = True
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request
…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 <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>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request
…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 <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>
srinivasreddy pushed a commit to srinivasreddy/cpython that referenced this pull request
…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 <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>
cmaloney pushed a commit to cmaloney/cpython that referenced this pull request
…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 <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>
encukou added a commit that referenced this pull request
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.
This was referenced
encukou added a commit that referenced this pull request
…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 <encukou@gmail.com>
encukou added a commit that referenced this pull request
…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 <encukou@gmail.com>
encukou added a commit that referenced this pull request
…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 <encukou@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters