bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840) (GH-27895)

miss-islington · roseman · web-flow · commit 986750be5c79 · 2021-08-22T21:05:46.000+02:00
- move description of internal modules (_tkinter and tkinter.constants) from section intro to list of additional modules at end of section, as not most important info - added missing ttk and tix here - emphasized up front that most apps will need tkinter and ttk (cherry picked from commit d5dbe8b) Co-authored-by: Mark Roseman <mark@markroseman.com>
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
@@ -67,23 +67,13 @@ installed, so you can read the Tcl/Tk documentation specific to that version.
 Tkinter Modules
 ---------------
 
-Most of the time, :mod:`tkinter` is all you really need, but a number of
-additional modules are available as well.  The Tk interface is located in a
-binary module named :mod:`_tkinter`. This module contains the low-level
-interface to Tk, and should never be used directly by application programmers.
-It is usually a shared library (or DLL), but might in some cases be statically
-linked with the Python interpreter.
-
-In addition to the Tk interface module, :mod:`tkinter` includes a number of
-Python modules, :mod:`tkinter.constants` being one of the most important.
-Importing :mod:`tkinter` will automatically import :mod:`tkinter.constants`,
-so, usually, to use Tkinter all you need is a simple import statement::
+Support for Tkinter is spread across several modules. Most applications will need the
+main :mod:`tkinter` module, as well as the :mod:`tkinter.ttk` module, which provides
+the modern themed widget set and API::
 
-   import tkinter
-
-Or, more often::
 
    from tkinter import *
+   from tkinter import ttk
 
 
 .. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)
@@ -106,7 +96,10 @@ Or, more often::
    subsystem initialized) by calling its :meth:`loadtk` method.
 
 
-Other modules that provide Tk support include:
+The modules that provide Tk support include:
+
+:mod:`tkinter`
+   Main Tkinter module.
 
 :mod:`tkinter.colorchooser`
    Dialog to let the user choose a color.
@@ -129,9 +122,35 @@ Other modules that provide Tk support include:
 :mod:`tkinter.simpledialog`
    Basic dialogs and convenience functions.
 
+:mod:`tkinter.ttk`
+   Themed widget set introduced in Tk 8.5, providing modern alternatives
+   for many of the classic widgets in the main :mod:`tkinter` module.
+
+Additional modules:
+
+:mod:`_tkinter`
+   A binary module that contains the low-level interface to Tcl/Tk.
+   It is automatically imported by the main :mod:`tkinter` module,
+   and should never be used directly by application programmers.
+   It is usually a shared library (or DLL), but might in some cases be
+   statically linked with the Python interpreter.
+
+:mod:`idlelib`
+   Python's Integrated Development and Learning Environment (IDLE). Based
+   on :mod:`tkinter`.
+
+:mod:`tkinter.constants`
+   Symbolic constants that can be used in place of strings when passing
+   various parameters to Tkinter calls. Automatically imported by the
+   main :mod:`tkinter` module.
+
 :mod:`tkinter.dnd`
-   Drag-and-drop support for :mod:`tkinter`. This is experimental and should
-   become deprecated when it is replaced  with the Tk DND.
+   (experimental) Drag-and-drop support for :mod:`tkinter`. This will
+   become deprecated when it is replaced with the Tk DND.
+
+:mod:`tkinter.tix`
+   (deprecated) An older third-party Tcl/Tk package that adds several new
+   widgets. Better alternatives for most can be found in :mod:`tkinter.ttk`.
 
 :mod:`turtle`
    Turtle graphics in a Tk window.
