Skip to content

Doc: errors tutorial improvements #16269

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

Merged
merged 9 commits into from
Jan 31, 2021

Conversation

adorilson
Copy link
Contributor

@adorilson adorilson commented Sep 19, 2019

Improvements:

  • Improvements in how try clause works section
    This suggestion is because the execution continues after except, not after try but before except. I guess this form more clear.

  • Surrounding some keywords with *...*
    For uniformity the highlighted terms

  • Adjust the number of chars per line to 80

Automerge-Triggered-By: GH:aeros

Review all try/except/raise/finally and surrounding
those without any mark (like :keyword:) with *...*.
Copy link
Contributor

@aeros aeros left a comment

Choose a reason for hiding this comment

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

Thanks for the PR @adorilson.

Regarding the usage of asterisks, they are typically reserved for argument names, so I do not support the idea of using try clause or except clause. If anything, the emphasis should only surround "try" or "except". Additionally, it should be using either the Spinx keyword role or inline code blocks. The Sphinx roles provide a specific functional purpose of linking to the documentation, so they are more beneficial when appropriately used.

Sphinx role example:

:keyword:`try` clause

Code block example:

``try`` clause

Also, while we typically require that any PRs changing or adding documentation fit within the 80 character line width limit for reST, it is discouraged to change an existing section solely for the purpose of fixing the wrapping, as this can add unnecessary clutter to the commit logs.

adorilson and others added 3 commits September 19, 2019 22:11
@adorilson
Copy link
Contributor Author

Hi, folks.

What exactly I need to do here?

Copy link
Contributor

@aeros aeros left a comment

Choose a reason for hiding this comment

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

Sorry for the delay, LGTM. (For clarification, I did not have commit privileges when I last left a review)

@miss-islington miss-islington merged commit 89294e3 into python:master Jan 31, 2021
adorilson added a commit to adorilson/cpython that referenced this pull request Mar 13, 2021
Improvements:

- Improvements in how try clause works section
  This suggestion is because the execution continues after *except*, not after *try* but before *except*. I guess this form more clear.

- Surrounding some keywords with \*...\*
  For uniformity the highlighted terms  

- Adjust the number of chars per line to 80
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 issue skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants