bpo-41762: Fix usage of productionlist markup in the doc by vstinner · Pull Request #22281 · python/cpython · GitHub

Use an unique identifier for the different grammars documented using
the Sphinx productionlist markup.

productionlist markups of the same grammar, like "expressions" or
"compound statements", use the same identifier.

https://bugs.python.org/issue41762

I checked manually the rendered HTML documentation: reference/expressions.html still contains clickable links between the different grammar items. For example, I can click on "expression" from lambda_expr and I'm pointed to expression definition of the "6.13. Conditional expressions" section. I also checked library/string.html: links are kept.

cc @JulienPalard @deronnax @isidentical @pablogsal @lysnikolaou

This change breaks the link to stmt_list.

Should we use the same identifier here, in expressions, simple statements and compound statements?

Yeah, I think that is a good idea (to preserve those links). Is there any other missing links between sections?

Or maybe use the least amount of namespaces possible?

I didn't check all modified pages.

@vstinner @pablogsal

I can check my PR works well after this PR is merged :)
#22198

Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier.

compound_stmts, expressions, simple_stmts and toplevel_components now use the "python-grammar" identifier for their "productionlist" markups.

Doc/reference/*.rst must all live in the same productionlist domain (same grammar):

top_level => compound_stmts => simple_stmts => expressions => lexical_analysis

Examples:

https://docs.python.org/dev/reference/toplevel_components.html#interactive-input : compound_stmt of interactive_input links to https://docs.python.org/dev/reference/compound_stmts.html#grammar-token-compound-stmt
https://docs.python.org/dev/reference/compound_stmts.html#grammar-token-stmt-list : simple_stmt of stmt_list links to: https://docs.python.org/dev/reference/simple_stmts.html#grammar-token-simple-stmt
https://docs.python.org/dev/reference/simple_stmts.html#grammar-token-expression-stmt : starred_expression of expression_stmt links to https://docs.python.org/dev/reference/expressions.html#grammar-token-starred-expression
https://docs.python.org/dev/reference/expressions.html#grammar-token-atom : identifier of atom links to: https://docs.python.org/dev/reference/lexical_analysis.html#grammar-token-identifier

Ok, I pushed a 3rd commit.

I checked links between reference/ documents and they all have been repaired by my 3rd commit.

I'm going to merge this PR once the CI pass.

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9.
🐍🍒⛏🤖

Sorry @vstinner, I had trouble checking out the 3.9 backport branch.
Please backport using cherry_picker on command line.
cherry_picker 8af239eacfcf52e4e0e2b0223e7cea4672309483 3.9

) Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>

GH-22300 is a backport of this pull request to the 3.8 branch.

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

) Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>

GH-22301 is a backport of this pull request to the 3.9 branch.

Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>

…H-22300) Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>

) Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar". (cherry picked from commit 8af239e) Co-authored-by: Victor Stinner <vstinner@python.org>

) Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier "python-grammar".

vstinner added skip news needs backport to 3.8 labels Sep 16, 2020

the-knights-who-say-ni added the CLA signed label Sep 16, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting core review labels Sep 16, 2020

pablogsal approved these changes Sep 16, 2020

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Sep 16, 2020

vstinner commented Sep 16, 2020

View reviewed changes

vstinner mentioned this pull request Sep 16, 2020

bpo-41490: Update ensurepip to install pip 20.2.1 and setuptools 49.2.1 #21748

Closed

corona10 approved these changes Sep 17, 2020

View reviewed changes

vstinner added 3 commits September 17, 2020 16:45

bpo-41762 : Fix usage of productionlist markup in the doc

f97d0e0

Use an unique identifier for the different grammars documented using the Sphinx productionlist markup. productionlist markups of the same grammar, like "expressions" or "compound statements", use the same identifier.

Use "python-grammar" identifier

f1905a6

compound_stmts, expressions, simple_stmts and toplevel_components now use the "python-grammar" identifier for their "productionlist" markups.

lexical_analysis also uses python-grammar

4fbcb97

vstinner merged commit 8af239e into python:master Sep 18, 2020

bedevere-bot removed the awaiting merge label Sep 18, 2020

vstinner deleted the production_list branch September 18, 2020 07:10

miss-islington assigned vstinner Sep 18, 2020

bedevere-bot removed the needs backport to 3.8 label Sep 18, 2020

vstinner added needs backport to 3.9 and removed needs backport to 3.9 labels Sep 18, 2020

bedevere-bot removed the needs backport to 3.9 label Sep 18, 2020

This was referenced Sep 18, 2020

Backport fails with no explaination, but work if retried python/miss-islington#389

Closed

bpo-35293: Remove RemovedInSphinx40Warning #22198

Merged

bpo-41762: Fix usage of productionlist markup in the doc by vstinner · Pull Request #22281 · python/cpython · GitHub

Uh oh!

Uh oh!

bpo-41762: Fix usage of productionlist markup in the doc - #22281

bpo-41762: Fix usage of productionlist markup in the doc#22281vstinner merged 3 commits intopython:masterpython/cpython:masterfrom vstinner:production_listCopy head branch name to clipboard

Conversation

vstinner commented Sep 16, 2020 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Sep 16, 2020

Uh oh!

vstinner Sep 16, 2020

Choose a reason for hiding this comment

Uh oh!

pablogsal Sep 16, 2020

Choose a reason for hiding this comment

Uh oh!

pablogsal Sep 16, 2020

Choose a reason for hiding this comment

Uh oh!

vstinner Sep 16, 2020

Choose a reason for hiding this comment

Uh oh!

corona10 left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Sep 17, 2020

Uh oh!

vstinner commented Sep 17, 2020

Uh oh!

miss-islington commented Sep 18, 2020

Uh oh!

miss-islington commented Sep 18, 2020

Uh oh!

bedevere-bot commented Sep 18, 2020

Uh oh!

miss-islington commented Sep 18, 2020

Uh oh!

bedevere-bot commented Sep 18, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bpo-41762: Fix usage of productionlist markup in the doc#22281
vstinner merged 3 commits into
python:masterfrom
vstinner:production_list

vstinner commented Sep 16, 2020 •
edited by bedevere-bot
Loading