gh-106996: Add the basics of a turtle graphics tutorial (#107072)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

diff --git a/Doc/includes/turtle-star.py b/Doc/includes/turtle-star.py
deleted file mode 100644 (file)
index 1a5db76..0000000
--- a/Doc/includes/turtle-star.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from turtle import *
-color('red', 'yellow')
-begin_fill()
-while True:
-    forward(200)
-    left(170)
-    if abs(pos()) < 1:
-        break
-end_fill()
-done()

diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index f14a677b7dd88c8af602a47bb3f7540c178e3b88..58ac546e75860b11ecf4df6575f0021f92d9543b 100644 (file)
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -24,6 +24,23 @@ introduced in Logo <https://en.wikipedia.org/wiki/Turtle_
 (robot)>`_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon
 in 1967.
 
+
+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
+   moves.
+
+   .. image:: turtle-star.*
+      :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.
 
@@ -38,26 +55,127 @@ graphical output it can be a way to do that without the overhead of
 introducing more complex or external libraries into their work.
 
 
-Get started
-===========
+Tutorial
+========
 
-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.
+New users should start here. In this tutorial we'll explore some of the
+basics of turtle drawing.
 
-.. sidebar:: Turtle star
 
-   Turtle can draw intricate shapes using programs that repeat simple
-   moves.
+Starting a turtle environment
+-----------------------------
 
-   .. image:: turtle-star.*
-      :align: center
+In a Python shell, import all the objects of the ``turtle`` module::
+
+    from turtle import *
+
+If you run into a ``No module named '_tkinter'`` error, you'll have to
+install the :mod:`Tk interface package <tkinter>` on your system.
+
+
+Basic drawing
+-------------
+
+Send the turtle forward 100 steps::
+
+   forward(100)
+
+You should see (most likely, in a new window on your display) a line
+drawn by the turtle, heading East. Change the direction of the turtle,
+so that it turns 120 degrees left (anti-clockwise)::
 
-   .. literalinclude:: ../includes/turtle-star.py
+   left(120)
 
-By combining together these and similar commands, intricate shapes and pictures
-can easily be drawn.
+Let's continue by drawing a triangle::
+
+   forward(100)
+   left(120)
+   forward(100)
+
+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()``.
+
+
+Pen control
+~~~~~~~~~~~
+
+Try changing the color - for example, ``color('blue')`` - and
+width of the line - for example, ``width(3)`` - and then drawing again.
+
+You can also move the turtle around without drawing, by lifting up the pen:
+``up()`` before moving. To start drawing again, use ``down()``.
+
+
+The turtle's position
+~~~~~~~~~~~~~~~~~~~~~
+
+Send your turtle back to its starting-point (useful if it has disappeared
+off-screen)::
+
+   home()
+
+The home position is at the center of the turtle's screen. If you ever need to
+know them, get the turtle's x-y co-ordinates with::
+
+    pos()
+
+Home is at ``(0, 0)``.
+
+And after a while, it will probably help to clear the window so we can start
+anew::
+
+   clearscreen()
+
+
+Making algorithmic patterns
+---------------------------
+
+Using loops, it's possible to build up geometric patterns::
+
+    for steps in range(100):
+        for c in ('blue', 'red', 'green'):
+            color(c)
+            forward(steps)
+            right(30)
+
+
+\ - which of course, are limited only by the imagination!
+
+Let's draw the star shape at the top of this page. We want red lines,
+filled in with yellow::
+
+    color('red')
+    fillcolor('yellow')
+
+Just as ``up()`` and ``down()`` determine whether lines will be drawn,
+filling can be turned on and off::
+
+    begin_fill()
+
+Next we'll create a loop::
+
+    while True:
+        forward(200)
+        left(170)
+        if abs(pos()) < 1:
+            break
+
+``abs(pos()) < 1`` is a good way to know when the turtle is back at its
+home position.
+
+Finally, complete the filling::
+
+    end_fill()
+
+(Note that filling only actually takes place when you give the
+``end_fill()`` command.)
+
+
+Explanation
+===========
 
 The :mod:`turtle` module is an extended reimplementation of the same-named
 module from the Python standard distribution up to version Python 2.5.
@@ -112,8 +230,8 @@ To use multiple turtles on a screen one has to use the object-oriented interface
    omitted here.
 
 
-Overview of available Turtle and Screen methods
-=================================================
+Turtle graphics reference
+=========================
 
 Turtle methods
 --------------