gh-157847: Rewrite turtle module docs introduction (#157854)

Author: StanFromIreland

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

Doc/library/turtle.rst

@@ -24,25 +24,6 @@
 
 --------------
 
-Introduction
-============
-
-Turtle graphics is an implementation of `the popular geometric drawing tools
-introduced in Logo <https://en.wikipedia.org/wiki/Turtle_
-(robot)>`_, 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
+<https://en.wikipedia.org/wiki/Turtle_(robot)>`_ 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`.
+   The python.org installers for Windows and macOS include it, but some
+   Linux distributions and other platforms may package it separately. If
+   ``import turtle`` fails with an error mentioning ``_tkinter``, look for
+   documentation from your distributor (that is, whoever provided Python to you).
+   Check this in advance if you're planning to use turtle graphics with a learner.
 
 
 .. _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 <turtle-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 <tkinter>` 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::
 

Doc/tools/removed-ids.txt

@@ -91,3 +91,7 @@ reference/expressions.html: generator.throw
 # 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