GeezerVison is showing github.com — Improve Tkinter Documentation · Issue #86726 · python/cpython
Improve Tkinter Documentation #86726Description
| BPO |
42560 |
| Nosy |
@terryjreedy, @roseman, @ambv, @serhiy-storchaka, @miss-islington, @E-Paine, @richardsheridan, @Hpmason, @ReblochonMasque, @simaoafonso-pwt |
| PRs |
gh-86726: Document more tkinter.Tk methods #23689bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState #27835bpo-42560: add warning to Tkinter docs about outdated pre-8.5 documentation online #27836bpo-42560: rework external references in Tkinter docs #27838bpo-42560: simplify/merge architecture info in Tkinter docs #27839bpo-42560: reorganize Tkinter docs modules section for clarity #27840bpo-42560: rewrite of Tkinter docs "life preserver" #27842[3.10] bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState (GH-27835) #27891[3.9] bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState (GH-27835) #27892[3.10] bpo-42560: rework external references in Tkinter docs (GH-27838) #27893[3.10] bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840) #27894[3.9] bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840) #27895[3.9] bpo-42560: rework external references in Tkinter docs (GH-27838) #27896[3.9] bpo-42560: rewrite of Tkinter docs "life preserver" (GH-27842) #27911[3.10] bpo-42560: rewrite of Tkinter docs "life preserver" (GH-27842) #27912[3.10] bpo-42560: add warning to Tkinter docs about outdated pre-8.5 documentation online (GH-27836) #27915[3.10] bpo-42560: simplify/merge architecture info in Tkinter docs (GH-27839) #27920 |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2020-12-03.18:35:37.011>
labels = ['3.11', 'type-feature', 'expert-tkinter', 'docs']
title = 'Improve Tkinter Documentation'
updated_at = <Date 2022-03-11.23:23:34.241>
user = 'https://github.com/hpmason' bugs.python.org fields:
activity = <Date 2022-03-11.23:23:34.241>
actor = 'markroseman'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Tkinter']
creation = <Date 2020-12-03.18:35:37.011>
creator = 'hpmason'
dependencies = []
files = []
hgrepos = []
issue_num = 42560
keywords = ['patch']
message_count = 37.0
messages = ['382437', '382725', '382800', '382802', '383964', '384022', '384031', '399428', '399458', '399476', '399478', '399627', '399630', '399678', '399694', '399704', '399743', '399765', '399782', '400088', '400089', '400091', '400093', '400094', '400095', '400096', '400097', '400098', '400160', '400164', '400169', '400170', '400173', '400189', '401673', '402082', '414946']
nosy_count = 13.0
nosy_names = ['effbot', 'terry.reedy', 'markroseman', 'docs@python', 'lukasz.langa', 'python-dev', 'serhiy.storchaka', 'miss-islington', 'epaine', 'Richard Sheridan', 'hpmason', 'ReblochonMasque', 'simao.afonso']
pr_nums = ['23689', '27835', '27836', '27838', '27839', '27840', '27842', '27891', '27892', '27893', '27894', '27895', '27896', '27911', '27912', '27915', '27920']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42560'
versions = ['Python 3.11'] Linked PRs
Activityhpmason commented on Dec 3, 2020 MannequinAuthor More actions E-Paine commented on Dec 8, 2020 See bpo-34154. I'm personally against such changes because we don't know what Tk version to write them for. Our documentation could be both outdated and too recent, including kwargs not available to some people (because they are running an older version).
The documentation available on third-party websites is pretty good and the official docs link to those. It is a shame Effbot is currently down, but the content is still available on https://web.archive.org/web/20201111145627/http://effbot.org/ hpmason commented on Dec 9, 2020 MannequinAuthor More actions Would it then be a good idea to add a link to the archive.org version of effbot? If so how best to add it to the documentation. The only other instances I can find links to archive.org in the documentation reference webpages that are down permanently, unlike effbot.
Docs/library/unittest.rst:55
Docs/library/xmlrpc.client.rst:52
Docs/using/windows.rst:1088
In the documentation, should we clarify that effbot is temporarily down and link to the archive.org, or just change the hyperlink (as in other instances above)? E-Paine commented on Dec 9, 2020 @fredrik, can you comment on when we might expect effbot.org to become available again? (i.e. is it worth us updating the docs to note that its down / changing the link to the Wayback Machine?) ReblochonMasque commented on Dec 29, 2020 I agree with @MasonGinter, the documentation is somewhat lacking. Relying on third parties is fragile - we were fortunate that the University of New Mexico Tech docs maintained by Pr. John W. Shipman were salvaged after his premature death; yet, some important example files were lost.
We now see effbot.org "taking a leave"... What other warnings do we need?
"we don't know what Tk version to write them for".
I don't understand why @epaine; shouldn't the docs be made available for the currently maintained version of python?
E-Paine commented on Dec 29, 2020
shouldn't the docs be made available for the currently maintained version of python?
Problem is the Tk version (which underpins tkinter) varies by distribution. Currently, Windows and MacOS Intel installers are packaged with 8.6.8, while MacOS Universal2 is soon to be packaged with a head later than 8.6.10. The situation gets worse on Linux, where different distros provide very different versions (CentOS 7, for example, runs Tk 8.5.13 which was released back in 2012). As the available options vary by version, we face an issue of what we actually describe in the docs.
As a side note, Shipman's docs are now also hosted at tkdocs.com/shipman, a site maintained by Mark Roseman, which should be more reliable than a github.io page (see bpo-37149 - he will also handle any copyright claims, etc. that may arise that meant we couldn't host it on docs.python.org). ReblochonMasque commented on Dec 29, 2020 Ah, I understand now, thank you for the clear explanation @epaine, appreciated. Thanks also for the link to Pr. Shipman's docs mirror on tkdocs.
It is not my place to argue what to do in such a case, but please allow me to re-emphasize the need for better tkinter documentation. It would, of course be imperfect, but not out of place to offer docs for the latest version of python, and the latest stable version of Tk? Even those that still have to rely on a previous version would surely find it useful.
Thank you for listening. roseman commented on Aug 12, 2021 I was having a peek at the main tkinter doc page again and would like to take a broader crack at it. I think most of what is there now (life preserver/reference) needs to be substantially reworked or trimmed.
I think exhaustive description of all methods etc. is unrealistic given the magnitude of the job and variation between versions, but it seems reasonable that the doc page would help identify what tkinter API to use, how to find out what it's parameters and options are (interactively), and if needed how to figure out the corresponding Tcl command so things can be looked up in the Tcl/Tk docs and in general map from Tcl to Python.
Ultimately, if the tkinter docs can get people started and point them to the right places to learn more (including things like the TkDocs tutorial or Shipman ref, the Tcl/Tk man pages) I'd call it a win. Right now it's a big muddle, and one that too easily becomes out-of-date. roseman commented on Aug 12, 2021 Here are my broad suggestions for improvement (each of these would turn into a separate PR). Thoughts for/against each?
-
'See also' section: use this to guide people to what they need. update to point out challenge of finding material given age etc., clearer what to use each resource for, update as needed (e.g. later editions of books)
-
Tkinter modules section: add ttk up front (i.e. usually use tkinter and tkinter.ttk), fill in a couple missing ones, move import/Tk() to later section (example or ref)
-
Architecture (was recently added). Merge in (and improve) material from how Tk and Tkinter are related, drop Tix from here
-
Replace life preserver with:
4a. Updated hello world example: use ttk and grid, explain each call
4b. How to introspect (figure out commands, arguments, and options... some of this is e.g. now in the reference section) so when don't have exact docs on something can figure out how to find answers
4c. Bridge from Tcl/Tk documentation: rewrite of 'quick look' and 'mapping' sections, more a list of how key concepts are realized in Tkinter, such as widget hierarchy. Less example based, more factual/reference oriented.
- 'Handy reference' section: drop most of what's there now, replace with lists of classes (e.g. widgets), general methods available on all widgets (grid, bind, winfo*, etc.), organized into categories. Likely without (most) arguments or options, or descriptions. There have been a few starts on this including the PR that Mason did here.
hpmason commented on Aug 12, 2021 MannequinAuthor More actions Those changes sound great to me, Mark. I've been busy with work and don't think I'll have the time to implement those changes. If you or someone else would like to work on this, I would gladly let you take over. E-Paine commented on Aug 12, 2021 Thank you for looking at this in great detail Mark and that all seems like a very useful set of changes! I've got a few more specific comments below, but they're mostly just small details.
-
I'd personally prefer alphabetical order (except Tix, which should be last because it's deprecated) with a note before / elsewhere that a tkinter / tkinter.ttk combination is generally be the best way to create GUIs (perhaps in with the hello world example?).
-
IMO this is suited better grouped with the other Tcl/Tk bridge documentation. I agree we should probably remove Tix from this section, since we're trying to dissuade people from using it.
-
This sounds very reasonable. The accompanying description and list of kwargs was what concerned me, but this sounds easily maintainable. Maybe we could group e.g. the winfo methods and link directly to the version-independent Tk man page for those (https://www.tcl.tk/man/tcl/TkCmd/winfo.html - so we don't need to keep changing the links)?
added 8 commits that reference this issue on Jul 11, 2026gh-86726: Fix and improve tkinter documentation and docstrings (GH-15… gh-86726: Note that the ttk Treeview separator column option needs Tk… [3.13] gh-86726: Note that the ttk Treeview separator column option n… [3.14] gh-86726: Note that the ttk Treeview separator column option n… [3.15] gh-86726: Note that the ttk Treeview separator column option n… added 4 commits that reference this issue on Jul 15, 2026gh-153550: Modernize the older prose sections of the tkinter document…
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|