bpo-19184: Update the documentation of dis module.

[mangrisano]

• Explain the behavior of the number of arguments of RAISE_VARGARGS
  opcode.

https://bugs.python.org/issue19184

[csabella]

Thanks for the contribution, @mangrisano! The CI failures are on the lines you added, but I have to research what the error means as I haven't encountered it before.

$ make check suspicious html SPHINXOPTS="-q -W -j4"
python3 tools/rstlint.py -i tools -i ./venv -i README.rst
[2] library/dis.rst:1118: default role used
[2] library/dis.rst:1120: default role used
[2] library/dis.rst:1121: default role used
[2] library/dis.rst:1122: default role used
[2] library/dis.rst:1123: default role used
5 problems with severity 2 found.
Makefile:183: recipe for target 'check' failed
make: *** [check] Error 1

[mangrisano]

Thanks for the contribution, @mangrisano! The CI failures are on the lines you added, but I have to research what the error means as I haven't encountered it before.

$ make check suspicious html SPHINXOPTS="-q -W -j4"
python3 tools/rstlint.py -i tools -i ./venv -i README.rst
[2] library/dis.rst:1118: default role used
[2] library/dis.rst:1120: default role used
[2] library/dis.rst:1121: default role used
[2] library/dis.rst:1122: default role used
[2] library/dis.rst:1123: default role used
5 problems with severity 2 found.
Makefile:183: recipe for target 'check' failed
make: *** [check] Error 1

The problem concerned the "`" when it wanted "``". First time for me as well. (Thanks Ezio for taking a look about it)

[csabella]

Thanks for fixing that so quickly; saved me the time. 🙂

[berkerpeksag]

Mostly cosmetic issues, otherwise it looks pretty good to me. Thanks!

[berkerpeksag]

This is a minor documentation change. We don't need to document it in a NEWS file. We only require NEWS entries for major documentation changes.

[mangrisano]

Ah, ok. I didn't know that. Thank you for the review.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[ezio-melotti]

Thanks for the contribution, @mangrisano! The CI failures are on the lines you added, but I have to research what the error means as I haven't encountered it before.

$ make check suspicious html SPHINXOPTS="-q -W -j4"
python3 tools/rstlint.py -i tools -i ./venv -i README.rst
[2] library/dis.rst:1118: default role used
...

To expand a bit on this: rest uses roles in the form of :name:`value` for inline markup (e.g. :func:`any`). The default role in the message refers to the "unnamed" default role, i.e. `value`, and we don't use that in the Python docs. (Not to be confused with ``value``, used for inline snippets of code).

The devguide talks about roles at https://devguide.python.org/documenting/#id4, but doesn't mention anything about the default role -- perhaps a PR to add an item to that list should be created.

[csabella]

Thanks @ezio-melotti! I wonder if it would help to add a cheat sheet (or FAQ) to the devguide too? For example, if you see x on the build then do y. Your explanation would fit in well with something like that and save a lot of time in troubleshooting.

[miss-islington]

Thanks @mangrisano for the PR, and @ezio-melotti for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

[miss-islington]

I'm having trouble backporting to 3.7. Reason: 'Error 110 while writing to socket. Connection timed out.'. Please retry by removing and re-adding the needs backport to 3.7 label.

[miss-islington]

Thanks @mangrisano for the PR, and @ezio-melotti for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

[bedevere-bot]

GH-13755 is a backport of this pull request to the 3.7 branch.