Skip to content
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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Sep 18, 2020
Merged

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

merged 3 commits into from
Sep 18, 2020

Conversation

vstinner
Copy link
Member

@vstinner vstinner commented Sep 16, 2020

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

@vstinner
Copy link
Member Author

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

@@ -85,7 +85,7 @@ Interactive input

Input in interactive mode is parsed using the following grammar:

.. productionlist::
.. productionlist:: interactive-input-component
interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change breaks the link to stmt_list.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or maybe use the least amount of namespaces possible?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't check all modified pages.

Copy link
Member

@corona10 corona10 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.
@vstinner
Copy link
Member Author

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.

@vstinner vstinner merged commit 8af239e into python:master Sep 18, 2020
@miss-islington
Copy link
Contributor

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

@vstinner vstinner deleted the production_list branch September 18, 2020 07:10
@miss-islington
Copy link
Contributor

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 18, 2020
)

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>
@bedevere-bot
Copy link

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

@vstinner vstinner added needs backport to 3.9 only security fixes and removed needs backport to 3.9 only security fixes labels Sep 18, 2020
@miss-islington
Copy link
Contributor

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 18, 2020
)

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>
@bedevere-bot
Copy link

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

@bedevere-bot bedevere-bot removed the needs backport to 3.9 only security fixes label Sep 18, 2020
miss-islington added a commit that referenced this pull request Sep 18, 2020
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>
vstinner added a commit that referenced this pull request Sep 18, 2020
…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>
ambv pushed a commit to ambv/cpython that referenced this pull request Oct 4, 2020
)

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>
xzy3 pushed a commit to xzy3/cpython that referenced this pull request Oct 18, 2020
)

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".
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants