Issue #10291: Backport 004fe3449193 with a few changes due to 22095.

terryjreedy · terryjreedy · commit 94ee51ed9ee1 · 2014-08-14T23:59:32.000-04:00
Will forward port 22095 changes separately.
diff --git a/Lib/turtledemo/__init__.py b/Lib/turtledemo/__init__.py
@@ -0,0 +1,14 @@
+"""
+    --------------------------------------
+        About this viewer
+    --------------------------------------
+
+    Tiny demo viewer to view turtle graphics example scripts.
+
+    Quickly and dirtyly assembled by Gregor Lingl.
+    June, 2006
+
+    For more information see: turtledemo - Help
+
+    Have fun!
+"""
diff --git a/Lib/turtledemo/__main__.py b/Lib/turtledemo/__main__.py
@@ -1,12 +1,95 @@
 #!/usr/bin/env python3
+
+"""
+  ----------------------------------------------
+      turtleDemo - Help
+  ----------------------------------------------
+
+  This document has two sections:
+
+  (1) How to use the demo viewer
+  (2) How to add your own demos to the demo repository
+
+
+  (1) How to use the demo viewer.
+
+  Select a demoscript from the example menu.
+  The (syntax coloured) source code appears in the left
+  source code window. IT CANNOT BE EDITED, but ONLY VIEWED!
+
+  - Press START button to start the demo.
+  - Stop execution by pressing the STOP button.
+  - Clear screen by pressing the CLEAR button.
+  - Restart by pressing the START button again.
+
+  SPECIAL demos are those which run EVENTDRIVEN.
+  (For example clock.py - or oldTurtleDemo.py which
+  in the end expects a mouse click.):
+
+      Press START button to start the demo.
+
+      - Until the EVENTLOOP is entered everything works
+      as in an ordinary demo script.
+
+      - When the EVENTLOOP is entered, you control the
+      application by using the mouse and/or keys (or it's
+      controlled by some timer events)
+      To stop it you can and must press the STOP button.
+
+      While the EVENTLOOP is running, the examples menu is disabled.
+
+      - Only after having pressed the STOP button, you may
+      restart it or choose another example script.
+
+   * * * * * * * *
+   In some rare situations there may occur interferences/conflicts
+   between events concerning the demo script and those concerning the
+   demo-viewer. (They run in the same process.) Strange behaviour may be
+   the consequence and in the worst case you must close and restart the
+   viewer.
+   * * * * * * * *
+
+
+   (2) How to add your own demos to the demo repository
+
+   - Place the file in the same directory as turtledemo/__main__.py
+     IMPORTANT! When imported, the demo should not modify the system
+     by calling functions in other modules, such as sys, tkinter, or
+     turtle. Global variables should be initialized in main().
+
+   - The code must contain a main() function which will
+     be executed by the viewer (see provided example scripts).
+     It may return a string which will be displayed in the Label below
+     the source code window (when execution has finished.)
+
+   - In order to run mydemo.py by itself, such as during development,
+     add the following at the end of the file:
+
+    if __name__ == '__main__':
+        main()
+        mainloop()  # keep window open
+
+    python -m turtledemo.mydemo  # will then run it
+
+   - If the demo is EVENT DRIVEN, main must return the string
+     "EVENTLOOP". This informs the demo viewer that the script is
+     still running and must be stopped by the user!
+
+     If an "EVENTLOOP" demo runs by itself, as with clock, which uses
+     ontimer, or minimal_hanoi, which loops by recursion, then the
+     code should catch the turtle.Terminator exception that will be
+     raised when the user presses the STOP button.  (Paint is not such
+     a demo; it only acts in response to mouse clicks and movements.)
+"""
 import sys
 import os
 
 from tkinter import *
 from idlelib.Percolator import Percolator
 from idlelib.ColorDelegator import ColorDelegator
-from idlelib.textView import view_file # TextViewer
+from idlelib.textView import view_text # TextViewer
 from importlib import reload
+from turtledemo import __doc__ as about_turtledemo
 
 import turtle
 import time
@@ -27,10 +110,10 @@ def getExampleEntries():
     return [entry[:-3] for entry in os.listdir(demo_dir) if
             entry.endswith(".py") and entry[0] != '_']
 
-help_entries = (  # (help_label,  help_file)
-    ('Turtledemo help', "demohelp.txt"),
-    ('About turtledemo', "about_turtledemo.txt"),
-    ('About turtle module', "about_turtle.txt"),
+help_entries = (  # (help_label,  help_doc)
+    ('Turtledemo help', __doc__),
+    ('About turtledemo', about_turtledemo),
+    ('About turtle module', turtle.__doc__),
     )
 
 class DemoWindow(object):
@@ -175,7 +258,7 @@ def makeHelpMenu(self):
 
         for help_label, help_file in help_entries:
             def show(help_label=help_label, help_file=help_file):
-                view_file(self.root, help_label, os.path.join(demo_dir, help_file))
+                view_text(self.root, help_label, help_file)
             CmdBtn.menu.add_command(label=help_label, font=menufont, command=show)
 
         CmdBtn['menu'] = CmdBtn.menu
