GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-101100: Fix Sphinx warnings in `turtle` module by hugovk · Pull Request #102340 · python/cpython

Conversation

@hugovk

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@hugovk
pythongh-101100: Fix Sphinx warnings in turtle module
7465127
@bedevere-bot bedevere-bot added the awaiting core review label Feb 28, 2023
@bedevere-bot bedevere-bot mentioned this pull request Feb 28, 2023
Fix all Sphinx reference warnings in the documentation #101100
Closed
@hugovk hugovk added the skip news label Feb 28, 2023
@CAM-Gerlach 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
CAM-Gerlach requested changes Mar 8, 2023
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
hugovk and others added 3 commits March 12, 2023 23:22
@hugovk @CAM-Gerlach
Apply suggestions from code review
d2e1474 
Co-authored-by: C.A.M. Gerlach <[email protected]>
@hugovk
Revert ~turtle. additions in table following '.. currentmodule:: turt…
0790e8c 
…le' addition
@hugovk
:func:x instead of :meth:turtle.x
a5633b2
@hugovk

hugovk commented Mar 12, 2023

Copy link
Copy Markdown
Member Author

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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
CAM-Gerlach
CAM-Gerlach reviewed Mar 13, 2023
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/turtle.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@hugovk @CAM-Gerlach
Apply suggestions from code review
e4dd0d8 
Co-authored-by: C.A.M. Gerlach <[email protected]>
CAM-Gerlach
CAM-Gerlach approved these changes Mar 13, 2023
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

LGTM, thanks @hugovk !

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@hugovk
hugovk merged commit 78e4e6c into python:main Mar 13, 2023
@miss-islington

miss-islington commented Mar 13, 2023

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk
hugovk deleted the docs-fix-turtle-warnings branch March 13, 2023 09:24
@bedevere-bot bedevere-bot removed the awaiting core review label Mar 13, 2023
@miss-islington

miss-islington commented Mar 13, 2023

Copy link
Copy Markdown
Contributor

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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@hugovk

hugovk commented Mar 13, 2023

Copy link
Copy Markdown
Member Author

Thank you for all the reviews!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@miss-islington miss-islington assigned hugovk Mar 13, 2023
@bedevere-bot

bedevere-bot commented Mar 13, 2023

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the needs backport to 3.10 label Mar 13, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Mar 13, 2023
@hugovk @CAM-Gerlach @miss-islington
pythongh-101100: Fix Sphinx warnings in turtle module (pythonGH-102340
c02a9c8 
)

(cherry picked from commit 78e4e6c)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
@hugovk hugovk added needs backport to 3.11 only security fixes and removed needs backport to 3.11 only security fixes labels Mar 13, 2023
@miss-islington

miss-islington commented Mar 13, 2023

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Mar 13, 2023
@hugovk @CAM-Gerlach @miss-islington
pythongh-101100: Fix Sphinx warnings in turtle module (pythonGH-102340
8481644 
)

(cherry picked from commit 78e4e6c)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
@bedevere-bot

bedevere-bot commented Mar 13, 2023

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Mar 13, 2023
hugovk added a commit to hugovk/cpython that referenced this pull request Mar 13, 2023
@hugovk
[3.11] pythongh-101100: Fix Sphinx warnings in turtle module (pytho…
3cfced0 
…nGH-102340)

Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit 78e4e6c)

Co-authored-by: Hugo van Kemenade <[email protected]>
miss-islington added a commit that referenced this pull request Mar 13, 2023
@miss-islington @hugovk @CAM-Gerlach
gh-101100: Fix Sphinx warnings in turtle module (GH-102340)
a01ad52 
(cherry picked from commit 78e4e6c)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this pull request Mar 13, 2023
@miss-islington @hugovk @CAM-Gerlach
gh-101100: Fix Sphinx warnings in turtle module (GH-102340)
c39a1d0 
(cherry picked from commit 78e4e6c)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
warsaw pushed a commit to warsaw/cpython that referenced this pull request Apr 11, 2023
@hugovk @CAM-Gerlach @warsaw
pythongh-101100: Fix Sphinx warnings in turtle module (python#102340)
341474a 
Co-authored-by: C.A.M. Gerlach <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@CAM-Gerlach CAM-Gerlach CAM-Gerlach approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@hugovk hugovk

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@hugovk @miss-islington @bedevere-bot @CAM-Gerlach
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.