gh-101100: Fix Sphinx warnings in `turtle` module by hugovk · Pull Request #102340 · python/cpython · GitHub

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

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.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

…le' addition

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

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.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

LGTM, thanks @hugovk !

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

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

Thank you for all the reviews!

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

) (cherry picked from commit 78e4e6c) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

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

) (cherry picked from commit 78e4e6c) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

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

…nGH-102340) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 78e4e6c) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

(cherry picked from commit 78e4e6c) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

pythongh-101100 : Fix Sphinx warnings in turtle module

7465127

bedevere-bot added the awaiting core review label Feb 28, 2023

bedevere-bot mentioned this pull request Feb 28, 2023

Fix all Sphinx reference warnings in the documentation #101100

Closed

hugovk added the skip news label Feb 28, 2023

CAM-Gerlach added docs Documentation in the Doc dir needs backport to 3.10 needs backport to 3.11 only security fixes labels Mar 8, 2023

CAM-Gerlach requested changes Mar 8, 2023

View reviewed changes

Comment thread Doc/library/turtle.rst Outdated

Comment thread Doc/library/turtle.rst

Comment thread Doc/library/turtle.rst Outdated

Comment thread Doc/library/turtle.rst Outdated

hugovk and others added 3 commits March 12, 2023 23:22

Apply suggestions from code review

d2e1474

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Revert ~turtle. additions in table following '.. currentmodule:: turt…

0790e8c

…le' addition

:func:x instead of :meth:turtle.x

a5633b2

CAM-Gerlach reviewed Mar 13, 2023

View reviewed changes

Apply suggestions from code review

e4dd0d8

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

CAM-Gerlach approved these changes Mar 13, 2023

View reviewed changes

hugovk merged commit 78e4e6c into python:main Mar 13, 2023

hugovk deleted the docs-fix-turtle-warnings branch March 13, 2023 09:24

bedevere-bot removed the awaiting core review label Mar 13, 2023

miss-islington assigned hugovk Mar 13, 2023

bedevere-bot removed the needs backport to 3.10 label Mar 13, 2023

hugovk added needs backport to 3.11 only security fixes and removed needs backport to 3.11 only security fixes labels Mar 13, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label Mar 13, 2023

warsaw pushed a commit to warsaw/cpython that referenced this pull request Apr 11, 2023

pythongh-101100 : Fix Sphinx warnings in turtle module (python#102340 )

341474a

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

gh-101100: Fix Sphinx warnings in `turtle` module by hugovk · Pull Request #102340 · python/cpython · GitHub

Repository navigation

gh-101100: Fix Sphinx warnings in turtle module - #102340

gh-101100: Fix Sphinx warnings in turtle module#102340hugovk merged 5 commits intopython:mainpython/cpython:mainfrom hugovk:docs-fix-turtle-warningshugovk/cpython:docs-fix-turtle-warningsCopy head branch name to clipboard

Conversation

hugovk commented Feb 28, 2023 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before

After

Uh oh!

CAM-Gerlach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk commented Mar 12, 2023

Uh oh!

CAM-Gerlach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Uh oh!

miss-islington commented Mar 13, 2023

Uh oh!

miss-islington commented Mar 13, 2023

Uh oh!

hugovk commented Mar 13, 2023

Uh oh!

bedevere-bot commented Mar 13, 2023

Uh oh!

miss-islington commented Mar 13, 2023

Uh oh!

bedevere-bot commented Mar 13, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gh-101100: Fix Sphinx warnings in turtle module#102340
hugovk merged 5 commits into
python:mainfrom
hugovk:docs-fix-turtle-warnings

hugovk commented Feb 28, 2023 •
edited by bedevere-bot
Loading

CAM-Gerlach left a comment •
edited
Loading

CAM-Gerlach left a comment •
edited
Loading