gh-153550: Modernize the older prose sections of the tkinter documentation#153647
Open
serhiy-storchaka wants to merge 2 commits into
Open
gh-153550: Modernize the older prose sections of the tkinter documentation#153647serhiy-storchaka wants to merge 2 commits into
serhiy-storchaka wants to merge 2 commits into
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
4 files changed± library/tk.html± library/tkinter.dnd.html± library/tkinter.html± library/tkinter.ttk.html |
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>
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
1 participant
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.