2424
2525--------------
2626
27- Introduction
28- ============
29-
30- Turtle graphics is an implementation of `the popular geometric drawing tools
31- introduced in Logo <https://en.wikipedia.org/wiki/Turtle_
32- (robot)>`_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon
33- in 1967.
34-
35- .. include:: ../includes/optional-module.rst
36-
37-
38- Get started
39- ===========
40-
41- Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the
42- command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the
43- direction it is facing, drawing a line as it moves. Give it the command
44- ``turtle.right(25)``, and it rotates in-place 25 degrees clockwise.
45-
4627.. sidebar:: Turtle star
4728
4829 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
5132 .. image:: turtle-star.png
5233 :align: center
5334
54- In Python, turtle graphics provides a representation of a physical "turtle"
55- (a little robot with a pen) that draws on a sheet of paper on the floor.
35+ Imagine a robotic turtle starting at (0, 0) in the x-y plane.
36+ After an ``import turtle``, give it the command ``turtle.forward(15)``, and it
37+ moves (on-screen!) 15 pixels in the direction it is facing, drawing a line as
38+ it moves. Give it the command ``turtle.right(25)``, and it rotates in-place 25
39+ degrees clockwise.
40+
41+ Turtle graphics is an implementation of `the drawing tools introduced in Logo
42+ <https://en.wikipedia.org/wiki/Turtle_(robot)>`_ in 1967. It was created as an
43+ educational tool, and its instant, visible feedback makes it an effective way
44+ for learners to encounter programming concepts. It is also a convenient way to
45+ produce simple graphical output without bringing in external libraries.
46+
47+ This document includes four main sections:
5648
57- It's an effective and well-proven way for learners to encounter
58- programming concepts and interaction with software, as it provides instant,
59- visible feedback. It also provides convenient access to graphical output
60- in general.
49+ * :ref:`turtle-tutorial` teaches the basics of turtle drawing.
50+ * :ref:`turtle-reference` describes the functions, methods and classes this
51+ module defines.
52+ * :ref:`turtle-howtos` details how to handle specific tasks.
53+ * :ref:`turtle-explanation` provides background on the object-oriented
54+ interface.
55+
56+ .. note::
6157
62- Turtle drawing was originally created as an educational tool, to be used by
63- teachers in the classroom. For the programmer who needs to produce some
64- graphical output it can be a way to do that without the overhead of
65- introducing more complex or external libraries into their work.
58+ Turtle graphics requires the :mod:`tkinter` :term:`optional module`.
59+ The python.org installers for Windows and macOS include it, but some
60+ Linux distributions and other platforms may package it separately. If
61+ ``import turtle`` fails with an error mentioning ``_tkinter``, look for
62+ documentation from your distributor (that is, whoever provided Python to you).
63+ Check this in advance if you're planning to use turtle graphics with a learner.
6664
6765
6866.. _turtle-tutorial:
67+ .. _get-started:
68+ .. _get-started-as-quickly-as-possible:
6969
7070Tutorial
7171========
@@ -108,7 +108,8 @@ Notice how the turtle, represented by an arrow, points in different
108108directions as you steer it.
109109
110110Experiment with those commands, and also with ``backward()`` and
111- ``right()``.
111+ ``right()``. Many commands also have terser aliases, such as ``fd()`` for
112+ :func:`forward`.
112113
113114
114115Pen control
@@ -188,38 +189,16 @@ Finally, complete the filling::
188189``end_fill()`` command.)
189190
190191
192+ .. _turtle-howtos:
191193.. _turtle-how-to:
194+ .. _how-to:
192195
193- How to...
194- =========
196+ How-to guides
197+ =============
195198
196199This section covers some typical turtle use-cases and approaches.
197200
198201
199- Get started as quickly as possible
200- ----------------------------------
201-
202- One of the joys of turtle graphics is the immediate, visual feedback that's
203- available from simple commands - it's an excellent way to introduce children
204- to programming ideas, with a minimum of overhead (not just children, of
205- course).
206-
207- The turtle module makes this possible by exposing all its basic functionality
208- as functions, available with ``from turtle import *``. The :ref:`turtle
209- graphics tutorial <turtle-tutorial>` covers this approach.
210-
211- It's worth noting that many of the turtle commands also have even more terse
212- equivalents, such as ``fd()`` for :func:`forward`. These are especially
213- useful when working with learners for whom typing is not a skill.
214-
215- .. _note:
216-
217- You'll need to have the :mod:`Tk interface package <tkinter>` installed on
218- your system for turtle graphics to work. Be warned that this is not
219- always straightforward, so check this in advance if you're planning to
220- use turtle graphics with a learner.
221-
222-
223202Automatically begin and end filling
224203-----------------------------------
225204
@@ -323,8 +302,11 @@ The turtle's screen can be customised, for example::
323302 t.screen.bgcolor("orange")
324303
325304
326- Turtle graphics reference
327- =========================
305+ .. _turtle-reference:
306+ .. _turtle-graphics-reference:
307+
308+ Reference
309+ =========
328310
329311.. note::
330312
0 commit comments