From ee251cf4103a99c037de77029eeb2eef4239f5a3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 20 Sep 2026 11:43:08 +0100 Subject: [PATCH 1/4] Rewrite `turtle` module docs introduction --- Doc/includes/optional-module.rst | 1 + Doc/library/turtle.rst | 95 ++++++++++++-------------------- 2 files changed, 37 insertions(+), 59 deletions(-) diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst index 262e73f2eaa09fb..d37f18227f73725 100644 --- a/Doc/includes/optional-module.rst +++ b/Doc/includes/optional-module.rst @@ -7,3 +7,4 @@ If you are the distributor, see :ref:`optional-module-requirements`. .. Similar notes appear in the docs of the modules: - zipfile - tarfile + - turtle diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index f28c4230f3d6b89..249004631ce9871 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -24,25 +24,6 @@ -------------- -Introduction -============ - -Turtle graphics is an implementation of `the popular geometric drawing tools -introduced in Logo `_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon -in 1967. - -.. include:: ../includes/optional-module.rst - - -Get started -=========== - -Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the -command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the -direction it is facing, drawing a line as it moves. Give it the command -``turtle.right(25)``, and it rotates in-place 25 degrees clockwise. - .. sidebar:: Turtle star Turtle can draw intricate shapes using programs that repeat simple @@ -51,18 +32,35 @@ direction it is facing, drawing a line as it moves. Give it the command .. image:: turtle-star.png :align: center -In Python, turtle graphics provides a representation of a physical "turtle" -(a little robot with a pen) that draws on a sheet of paper on the floor. +Imagine a robotic turtle starting at (0, 0) in the x-y plane. +After an ``import turtle``, give it the command ``turtle.forward(15)``, and it +moves (on-screen!) 15 pixels in the direction it is facing, drawing a line as +it moves. Give it the command ``turtle.right(25)``, and it rotates in-place 25 +degrees clockwise. + +Turtle graphics is an implementation of `the drawing tools introduced in Logo +`_ in 1967. It was created as an +educational tool, and its instant, visible feedback makes it an effective way +for learners to encounter programming concepts. It is also a convenient way to +produce simple graphical output without bringing in external libraries. + +This document includes four main sections: -It's an effective and well-proven way for learners to encounter -programming concepts and interaction with software, as it provides instant, -visible feedback. It also provides convenient access to graphical output -in general. +* :ref:`turtle-tutorial` teaches the basics of turtle drawing. +* :ref:`turtle-reference` describes the functions, methods and classes this + module defines. +* :ref:`turtle-howtos` details how to handle specific tasks. +* :ref:`turtle-explanation` provides background on the object-oriented + interface. + +.. note:: -Turtle drawing was originally created as an educational tool, to be used by -teachers in the classroom. For the programmer who needs to produce some -graphical output it can be a way to do that without the overhead of -introducing more complex or external libraries into their work. + Turtle graphics requires the :mod:`tkinter` :term:`optional module`. + Installing it is not always straightforward, so check this in advance if + you're planning to use turtle graphics with a learner. + If it is missing from your copy of CPython, + look for documentation from your distributor (that is, + whoever provided Python to you). .. _turtle-tutorial: @@ -108,7 +106,8 @@ Notice how the turtle, represented by an arrow, points in different directions as you steer it. Experiment with those commands, and also with ``backward()`` and -``right()``. +``right()``. Many commands also have terser aliases, such as ``fd()`` for +:func:`forward`. Pen control @@ -188,38 +187,14 @@ Finally, complete the filling:: ``end_fill()`` command.) -.. _turtle-how-to: +.. _turtle-howtos: -How to... -========= +How-to guides +============= This section covers some typical turtle use-cases and approaches. -Get started as quickly as possible ----------------------------------- - -One of the joys of turtle graphics is the immediate, visual feedback that's -available from simple commands - it's an excellent way to introduce children -to programming ideas, with a minimum of overhead (not just children, of -course). - -The turtle module makes this possible by exposing all its basic functionality -as functions, available with ``from turtle import *``. The :ref:`turtle -graphics tutorial ` covers this approach. - -It's worth noting that many of the turtle commands also have even more terse -equivalents, such as ``fd()`` for :func:`forward`. These are especially -useful when working with learners for whom typing is not a skill. - -.. _note: - - You'll need to have the :mod:`Tk interface package ` installed on - your system for turtle graphics to work. Be warned that this is not - always straightforward, so check this in advance if you're planning to - use turtle graphics with a learner. - - Automatically begin and end filling ----------------------------------- @@ -323,8 +298,10 @@ The turtle's screen can be customised, for example:: t.screen.bgcolor("orange") -Turtle graphics reference -========================= +.. _turtle-reference: + +Reference +========= .. note:: From b37c46eb00e12f7d8d9fe4d9c910c6daece18048 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 20 Sep 2026 11:46:52 +0100 Subject: [PATCH 2/4] Preserve anchors --- Doc/library/turtle.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 249004631ce9871..e3e7f05972ac607 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -24,6 +24,8 @@ -------------- +.. _introduction: + .. sidebar:: Turtle star Turtle can draw intricate shapes using programs that repeat simple @@ -64,6 +66,8 @@ This document includes four main sections: .. _turtle-tutorial: +.. _get-started: +.. _get-started-as-quickly-as-possible: Tutorial ======== @@ -188,6 +192,8 @@ Finally, complete the filling:: .. _turtle-howtos: +.. _turtle-how-to: +.. _how-to: How-to guides ============= @@ -299,6 +305,7 @@ The turtle's screen can be customised, for example:: .. _turtle-reference: +.. _turtle-graphics-reference: Reference ========= From f95996438c29bc99d0808b980ed6f2ad2b2e6a86 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 20 Sep 2026 11:55:43 +0100 Subject: [PATCH 3/4] Oops, missed one, but it was never used anyway. --- Doc/tools/removed-ids.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index d3e4d581bbc9e8c..6b7c1dbeb3ce75a 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -89,3 +89,6 @@ library/dialog.html: (page missing) # Obsolete sections in 'turtle' docs library/turtle.html: changes-since-python-2-6 library/turtle.html: changes-since-python-3-0 + +# 'turtle' documentation reorganisation (gh-157847) +library/turtle.html: note From 87ab8fb30f9cc8c2d9d3e0b57d9527e3e5dfb2ff Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 20 Sep 2026 12:01:05 +0100 Subject: [PATCH 4/4] Remove `introduction` label to not conflict with other such labels --- Doc/library/turtle.rst | 2 -- Doc/tools/removed-ids.txt | 1 + 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index e3e7f05972ac607..362e76927cdec94 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -24,8 +24,6 @@ -------------- -.. _introduction: - .. sidebar:: Turtle star Turtle can draw intricate shapes using programs that repeat simple diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index 6b7c1dbeb3ce75a..05e374cb0637df5 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -92,3 +92,4 @@ library/turtle.html: changes-since-python-3-0 # 'turtle' documentation reorganisation (gh-157847) library/turtle.html: note +library/turtle.html: introduction