gh-101100: Fix Sphinx warnings in turtle module

[hugovk]

Fixes 36 Sphinx warnings.

Before

$ make html SPHINXERRORHANDLING=-n 2>&1 | grep turtle.rst | tee >(wc -l)
/Users/hugo/github/cpython/Doc/library/turtle.rst:58: WARNING: py:class reference target not found: tkinter.Canvas
/Users/hugo/github/cpython/Doc/library/turtle.rst:75: WARNING: py:class reference target not found: Pen
/Users/hugo/github/cpython/Doc/library/turtle.rst:1547: WARNING: py:meth reference target not found: addcomponent
/Users/hugo/github/cpython/Doc/library/turtle.rst:2111: WARNING: py:class reference target not found: tkinter.Canvas
/Users/hugo/github/cpython/Doc/library/turtle.rst:2126: WARNING: py:class reference target not found: tkinter.Canvas
/Users/hugo/github/cpython/Doc/library/turtle.rst:2128: WARNING: py:func reference target not found: setbg
/Users/hugo/github/cpython/Doc/library/turtle.rst:2343: WARNING: py:meth reference target not found: Screen.setup
/Users/hugo/github/cpython/Doc/library/turtle.rst:2345: WARNING: py:meth reference target not found: Screen.screensize
/Users/hugo/github/cpython/Doc/library/turtle.rst:2407: WARNING: py:func reference target not found: tracer
/Users/hugo/github/cpython/Doc/library/turtle.rst:2407: WARNING: py:func reference target not found: update
/Users/hugo/github/cpython/Doc/library/turtle.rst:2419: WARNING: py:func reference target not found: ondrag
/Users/hugo/github/cpython/Doc/library/turtle.rst:2436: WARNING: py:func reference target not found: onclick
/Users/hugo/github/cpython/Doc/library/turtle.rst:2442: WARNING: py:func reference target not found: stamp
/Users/hugo/github/cpython/Doc/library/turtle.rst:2445: WARNING: py:class reference target not found: Vec2D
/Users/hugo/github/cpython/Doc/library/turtle.rst:2448: WARNING: py:func reference target not found: clone
/Users/hugo/github/cpython/Doc/library/turtle.rst:2448: WARNING: py:func reference target not found: undo
/Users/hugo/github/cpython/Doc/library/turtle.rst:2458: WARNING: py:func reference target not found: clone
/Users/hugo/github/cpython/Doc/library/turtle.rst:2464: WARNING: py:func reference target not found: circle
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:meth reference target not found: Turtle.tracer
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:meth reference target not found: Turtle.window_width
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:meth reference target not found: Turtle.window_height
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:class reference target not found: Screen
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:class reference target not found: TurtleScreen
/Users/hugo/github/cpython/Doc/library/turtle.rst:2472: WARNING: py:class reference target not found: Screen
/Users/hugo/github/cpython/Doc/library/turtle.rst:2480: WARNING: py:meth reference target not found: Turtle.fill
/Users/hugo/github/cpython/Doc/library/turtle.rst:2480: WARNING: py:meth reference target not found: begin_fill
/Users/hugo/github/cpython/Doc/library/turtle.rst:2480: WARNING: py:meth reference target not found: end_fill
/Users/hugo/github/cpython/Doc/library/turtle.rst:2485: WARNING: py:meth reference target not found: Turtle.filling
/Users/hugo/github/cpython/Doc/library/turtle.rst:2493: WARNING: py:meth reference target not found: Turtle.shearfactor
/Users/hugo/github/cpython/Doc/library/turtle.rst:2493: WARNING: py:meth reference target not found: Turtle.shapetransform
/Users/hugo/github/cpython/Doc/library/turtle.rst:2493: WARNING: py:meth reference target not found: Turtle.get_shapepoly
/Users/hugo/github/cpython/Doc/library/turtle.rst:2493: WARNING: py:meth reference target not found: Turtle.tiltangle
/Users/hugo/github/cpython/Doc/library/turtle.rst:2493: WARNING: py:meth reference target not found: Turtle.settiltangle
/Users/hugo/github/cpython/Doc/library/turtle.rst:2500: WARNING: py:meth reference target not found: Screen.onkeypress
/Users/hugo/github/cpython/Doc/library/turtle.rst:2500: WARNING: py:meth reference target not found: Screen.onkey
/Users/hugo/github/cpython/Doc/library/turtle.rst:2500: WARNING: py:meth reference target not found: Screen.onkeyrelease
/Users/hugo/github/cpython/Doc/library/turtle.rst:2504: WARNING: py:meth reference target not found: Screen.mainloop
/Users/hugo/github/cpython/Doc/library/turtle.rst:2504: WARNING: py:func reference target not found: mainloop
/Users/hugo/github/cpython/Doc/library/turtle.rst:2508: WARNING: py:meth reference target not found: Screen.textinput
/Users/hugo/github/cpython/Doc/library/turtle.rst:2508: WARNING: py:meth reference target not found: Screen.numinput
      40

After

$ make html SPHINXERRORHANDLING=-n 2>&1 | grep turtle.rst | tee >(wc -l)
/Users/hugo/github/cpython/Doc/library/turtle.rst:58: WARNING: py:class reference target not found: tkinter.Canvas
/Users/hugo/github/cpython/Doc/library/turtle.rst:75: WARNING: py:class reference target not found: turtle.Pen
/Users/hugo/github/cpython/Doc/library/turtle.rst:2111: WARNING: py:class reference target not found: tkinter.Canvas
/Users/hugo/github/cpython/Doc/library/turtle.rst:2126: WARNING: py:class reference target not found: tkinter.Canvas
       4

I think the tkinter.Canvas ones are valid because I don't see Canvas in /~https://github.com/python/cpython/blob/main/Doc/library/tkinter.rst

And I'm not sure how to deal with turtle.Pen, it's defined like:

cpython/Lib/turtle.py

Line 3836 in 880437d

Pen = Turtle

where:

cpython/Lib/turtle.py

Line 3816 in 880437d

class Turtle(RawTurtle):

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[CAM-Gerlach]

Some top-level comments (some also reflected in individual suggestions):

• The turtle.* callables are actually documented as module-level functions, rather than class-level methods on their specific class. ISTM that they should ideally be primarily documented as methods of their particular class, to be clear and explicit where each comes from and their recommended usage pattern, but I'm still working on a clean way to redirect these to avoid breaking existing references. So, at least for now the current definitions will have to do, but I would suggest at least using the correct role (func rather than meth), and omitting the turtle which implies they are methods of a turtle class (rather than their actual class.
• Particularly in places where the actual class name is used, instead of erasing that information, I suggest instead making that the explicit title of the reference. Then, readers still have that info, and we can more easily go back later to have it point to the class if we end up moving and directing things.
• If you use currentmodule where indicated, you can revert most of the noisy changes below that line.

[hugovk]

Thank you for the review!

Remaining warnings:

$ make -C Doc html SPHINXERRORHANDLING=-n 2>&1 | grep turtle.rst | tee >(wc -l)
/Users/huvankem/github/cpython/Doc/library/turtle.rst:58: WARNING: py:class reference target not found: tkinter.Canvas
/Users/huvankem/github/cpython/Doc/library/turtle.rst:75: WARNING: py:class reference target not found: Pen
/Users/huvankem/github/cpython/Doc/library/turtle.rst:1: WARNING: py:class reference target not found: tkinter.Canvas
/Users/huvankem/github/cpython/Doc/library/turtle.rst:1: WARNING: py:class reference target not found: tkinter.Canvas
       4

[CAM-Gerlach]

Thanks! I had some follow-up suggestions mostly related to the second point above,

Particularly in places where the actual class name is used, instead of erasing that information, I suggest instead making that the explicit title of the reference. Then, readers still have that info, and we can more easily go back later to have it point to the class if we end up moving and directing things.

In particular, a number of them didn't actually make sense anymore when the prose and reference text no longer referred to the class/method.

[CAM-Gerlach]

LGTM, thanks @hugovk !

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry @hugovk, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 78e4e6c3d71980d4e6687f07afa6ddfc83e29b04 3.11

[hugovk]

Thank you for all the reviews!

[bedevere-bot]

GH-102638 is a backport of this pull request to the 3.10 branch.

[miss-islington]

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

[bedevere-bot]

GH-102639 is a backport of this pull request to the 3.11 branch.