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..362e76927cdec94 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,21 +32,40 @@ 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: +.. _get-started: +.. _get-started-as-quickly-as-possible: Tutorial ======== @@ -108,7 +108,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 +189,16 @@ Finally, complete the filling:: ``end_fill()`` command.) +.. _turtle-howtos: .. _turtle-how-to: +.. _how-to: -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 +302,11 @@ The turtle's screen can be customised, for example:: t.screen.bgcolor("orange") -Turtle graphics reference -========================= +.. _turtle-reference: +.. _turtle-graphics-reference: + +Reference +========= .. note:: diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index d3e4d581bbc9e8c..05e374cb0637df5 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -89,3 +89,7 @@ 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 +library/turtle.html: introduction