bpo-35044: Use the :exc: role for the exceptions in the doc #10037
Conversation
Doc/howto/functional.rst
Outdated
| Inside a generator function, ``return value`` causes ``StopIteration(value)`` | ||
| to be raised from the :meth:`~generator.__next__` method. Once this happens, or | ||
| the bottom of the function is reached, the procession of values ends and the | ||
| Inside a generator function, ``return value`` causes :exc:`StopIteration` to be |
There was a problem hiding this comment.
The current wording is more correct. StopIteration(value) will be raised.
Doc/whatsnew/3.5.rst
Outdated
| @@ -560,15 +560,15 @@ PEP 479: Change StopIteration handling inside generators | |||
|
|
|||
| The interaction of generators and :exc:`StopIteration` in Python 3.4 and | |||
| earlier was sometimes surprising, and could conceal obscure bugs. Previously, | |||
| ``StopIteration`` raised accidentally inside a generator function was | |||
| :exc:`StopIteration` raised accidentally inside a generator function was | |||
There was a problem hiding this comment.
There is a link to StopIteration above. Too many links to the same target distract attention.
|
@serhiy-storchaka do you want to continue the review? thank you |
Doc/faq/design.rst
Outdated
| would raise a KeyError exception because the id of the ``[1, 2]`` used in the | ||
| second line differs from that in the first line. In other words, dictionary | ||
| keys should be compared using ``==``, not using :keyword:`is`. | ||
| would raise a :exc:`KeyError` exception because the id of the ``[1, 2]`` used |
There was a problem hiding this comment.
Please leave "in the" on the same line to reduce the number of modified lines in your change. It's fine if the line is "too long".
Doc/howto/functional.rst
Outdated
| @@ -482,8 +482,8 @@ Here's a sample usage of the ``generate_ints()`` generator: | |||
| You could equally write ``for i in generate_ints(5)``, or ``a, b, c = | |||
| generate_ints(3)``. | |||
|
|
|||
| Inside a generator function, ``return value`` causes ``StopIteration(value)`` | |||
| to be raised from the :meth:`~generator.__next__` method. Once this happens, or | |||
| Inside a generator function, ``return value`` causes ``StopIteration(value)`` to | |||
|
@vstinner updated, thanks for your review. |
Doc/whatsnew/3.6.rst
Outdated
| @@ -1200,7 +1200,7 @@ importlib | |||
|
|
|||
| Import now raises the new exception :exc:`ModuleNotFoundError` | |||
| (subclass of :exc:`ImportError`) when it cannot find a module. Code | |||
| that current checks for ``ImportError`` (in try-except) will still work. | |||
| that current checks for :exc:`ImportError` in try-except) will still work. | |||
There was a problem hiding this comment.
There is already a link to this exception in this paragraph.
There was a problem hiding this comment.
I don't think that it's an issue. I prefer to always use :exc: role to always have the same formatting.
There was a problem hiding this comment.
If you want to get the same formatting, you can use :exc:`!ImportError`. But it is more verbose.
Since the formatting is not missed, but it just don't create a link, I'm sure this was done for purpose.
There was a problem hiding this comment.
I don't why it's an issue to have two links to the same exception in the same paragraph. IMHO it's a good thing :)
There was a problem hiding this comment.
suggestions? remove/keep? tell me ;-)
thanks
There was a problem hiding this comment.
Links have many disadvantages:
- They distract attention.
- Unintentional mouse click causes loading different page.
- It is harder to copy linked text.
- They increase the html file size and the time of its loading and rendering.
Links have great advantages which overwhelm disadvantages. But if repeat the same link multiple times, its advantages are left constant, while disadvantages are increased with every repetition.
There was a problem hiding this comment.
@serhiy-storchaka done, thanks
Doc/whatsnew/3.7.rst
Outdated
| @@ -1393,7 +1393,7 @@ The subprocess module is now more graceful when handling | |||
| :exc:`KeyboardInterrupt` during :func:`subprocess.call`, | |||
| :func:`subprocess.run`, or in a :class:`~subprocess.Popen` | |||
| context manager. It now waits a short amount of time for the child | |||
| to exit, before continuing the handling of the ``KeyboardInterrupt`` | |||
| to exit, before continuing the handling of the :exc:`KeyboardInterrupt` | |||
There was a problem hiding this comment.
There is already a link to this exception in this paragraph.
| @@ -0,0 +1 @@ | |||
| Fix the documentation with the role exc for the appropriated exception. | |||
There was a problem hiding this comment.
"Patch by ..."
And perhaps highlight "exc"? ``exc``
There was a problem hiding this comment.
+1 to format properly "exc" :) I hesitated to ask the same change.
There was a problem hiding this comment.
@serhiy-storchaka I wanted to use :exc: but there was an exception during the build process of the doc. it's the reason why I simply used exc, but ok I am going to change that. Thanks
|
Thanks @matrixise for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.6, 3.7. |
|
GH-10122 is a backport of this pull request to the 3.7 branch. |
(cherry picked from commit e483f02) Co-authored-by: Stéphane Wirtel <stephane@wirtel.be>
|
Sorry, @matrixise and @vstinner, I could not cleanly backport this to |
If the backport cannot be automated, I don't think that it's worth it. Thanks @matrixise for your contribution and @serhiy-storchaka for the review ;-) |
https://bugs.python.org/issue35044