gh-153550: Modernize the older prose sections of the tkinter documentation#153647
Merged
serhiy-storchaka merged 3 commits intoJul 15, 2026
Merged
Conversation
…cumentation Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (pythongh-86726 and pythongh-153549). * Rework "The packer" into a general "Geometry management" section that covers grid, pack and place, with a short example and use case for each, presents grid as the flexible default, and warns against mixing pack and grid in one container. Add symmetric cross-links between the Grid, Pack and Place reference classes and this section. * Rework "The window manager": explain what the window manager is, state that the Wm mixin is inherited by Tk and Toplevel so its methods are called directly on a top-level window, and replace the dated App(Frame) example (which reached the window through master) with a direct Tk() example. Drop the private _root() aside and cross-link the section and the Wm reference class to each other. * Rework "Coupling widget variables": explain that a widget links to a Variable object rather than a plain Python variable because Python cannot notify Tk when a variable is reassigned, and replace the dated App(Frame) example (whose entry was attached to the wrong parent) with a direct ttk example showing both get() and set(). * Remove the page-number citations to Ousterhout's book and point to the relevant Tk man pages instead. * Refresh the Tcl/Tk links in tkinter.ttk: add the official ttk::intro man page as the current explanation of the theme engine, keep Joe English's illustrated 2004 "Tile Widget Set" paper for its element and layout diagrams, and drop the now-redundant conversion monograph. * Modernize the tkinter.ttk front matter: lead the introduction with the native-theme benefit instead of peripheral features, update the TIP 48 link to its canonical URL, and add a note recommending the explicit "from tkinter import ttk" form over the star-import override. * Add cross-references between the two documents: point the tkinter.ttk introduction at the shared concepts documented for tkinter, and link the themed-widgets note in the tkinter introduction to tkinter.ttk. * Reconcile the "Packer options" and "Tk option data types" lists with the reference: replace the incomplete packer list with a cross-link to Pack.pack_configure, and frame the data-types list as the shared value types the reference refers to. * Fill in the empty Entry index list under "The index parameter", and describe "@6" as a string rather than an integer. * Point the classic base-widget examples at the themed ttk widgets. * Fix the malformed target-selection list in tkinter.dnd: make it a single ordered list with the sub-steps nested under the search step, and mark up "source" and "event" as parameters. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5 tasks
Documentation build overview
11 files changed ·
|
serhiy-storchaka
added
needs backport to 3.13
Renaming the "The packer" section to "Geometry management" and folding away the "Packer options" subsection removed their implicit HTML ids, breaking existing deep links. Restore both as explicit targets on the new section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
terryjreedy
requested changes
Jul 15, 2026
terryjreedy
left a comment
terryjreedy
left a comment
Member
There was a problem hiding this comment.
I mostly ignored sphinx formatting, focusing on content. Many chunks are improved. Only a few suggestions.
|
When you're done making the requested changes, leave the comment: |
…etry docs Address review comments: forward-reference the grid/pack warning from the geometry managers intro, and mention that frames and toplevels are containers too (toplevels being managed by the window manager). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Member
Author
|
I have made the requested changes; please review again. |
|
Thanks for making the requested changes! @terryjreedy: please review the changes made to this pull request. |
Member
Author
|
I merged suggestions on my side because they needed re-wraping the lines. |
terryjreedy
approved these changes
Jul 15, 2026
|
Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15. |
|
GH-153773 is a backport of this pull request to the 3.15 branch. |
bedevere-app
Bot
removed
the
needs backport to 3.15
|
Sorry, @serhiy-storchaka, I could not cleanly backport this to |
|
GH-153774 is a backport of this pull request to the 3.14 branch. |
serhiy-storchaka
added a commit
that referenced
this pull request
Jul 15, 2026
…ocumentation (GH-153647) (GH-153774) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
serhiy-storchaka
added a commit
that referenced
this pull request
Jul 15, 2026
…ocumentation (GH-153647) (GH-153773) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
GH-153775 is a backport of this pull request to the 3.13 branch. |
serhiy-storchaka
added a commit
that referenced
this pull request
Jul 15, 2026
…ocumentation (GH-153647) (GH-153775) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up of gh-86726, closing gh-153550.
The
tkinterreference sections were overhauled in gh-86726 and #153549, but the narrative prose preceding them — Tkinter life preserver and Handy reference inDoc/library/tkinter.rst, plus thetkinter.ttkfront matter — still read like a late-1990s tutorial. This is an editorial pass to match. No API changes.tkinter.rstgrid,packandplace, with an example and use case for each,gridas the default, and a warning against mixingpackandgridin one container.Tk()/ttkexamples instead of the datedApp(Frame)idiom, and correct explanations (e.g. a widget links to aVariablebecause Python can't notify Tk when a plain variable is reassigned).ttkwidgets.tkinter.ttk.rstfrom tkinter import ttkform; refresh the theme-engine links (ttk::intro+ the illustrated Tile Widget Set paper); add cross-references totkinter.rst.tkinter.dnd.rstDocs-only; no
Misc/NEWS.dentry.