Skip to content

gh-157847: Improve more turtle docstrings and docs - #158562

Open
StanFromIreland wants to merge 4 commits into
python:mainfrom
StanFromIreland:turtle/more-docstings
Open

StanFromIreland wants to merge 4 commits into
python:mainfrom
StanFromIreland:turtle/more-docstings

Conversation

@StanFromIreland

@StanFromIreland StanFromIreland commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

This continues the work started in #158281 and #158330. It improves the reference docs and docstrings, modernising them, making them easier to understand/clearer, and consistent.

Yes, a few could reasonably be classified as churn, however, the turtle module is, frankly, quite messy in places. I think these changes improve readability and, as a result, maintainability, so I intend to tidy up similar issues. They should also have relatively little impact on useful Git history, since the majority of the affected lines date back to the original port in 97cf99f.

@read-the-docs-community

read-the-docs-community Bot commented Oct 1, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #34886064 | 📁 Comparing f3f5085 against main (0906d2a)

  🔍 Preview build  

2 files changed
± library/turtle.html
± whatsnew/changelog.html

@terryjreedy

Copy link
Copy Markdown
Member

To review, I needed to experiment. To refresh my memory, I followed the tutorial. In "Starting a turtle environment", the import is insufficient. It does not 'start a turtle environment'. Add reset() to the code example and text "The reset command opens a default screen with a default turtle at its default position and orientation." directly below. Starting with forward 'worked' in that it first calls reset, but it was jarring and uncomfortable doing so when there was nothing visible.

I would add this to this PR.

Co-authored-by: Terry Reedy <tjreedy@udel.edu>
@StanFromIreland

Copy link
Copy Markdown
Member Author

Yeah, the tutorial (like all of the sections) needs some work. But, I'm happy to apply your suggestion now if that aids reviewing :-) However, I switched reset() for showturtle().

Comment thread Doc/library/turtle.rst Outdated
@bedevere-app

bedevere-app Bot commented Oct 1, 2026

Copy link
Copy Markdown

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

@terryjreedy

Copy link
Copy Markdown
Member

Yes, showturtle() is a better name with the same visible effect.

Co-authored-by: Terry Reedy <tjreedy@udel.edu>
@StanFromIreland

Copy link
Copy Markdown
Member Author

I have made the requested changes; please review again

@bedevere-app

bedevere-app Bot commented Oct 1, 2026

Copy link
Copy Markdown

Thanks for making the requested changes!

@terryjreedy: please review the changes made to this pull request.

@bedevere-app
bedevere-app Bot requested a review from terryjreedy October 1, 2026 20:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants