Improve Tkinter Documentation

[hpmason]

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 #23689 bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState #27835 bpo-42560: add warning to Tkinter docs about outdated pre-8.5 documentation online #27836 bpo-42560: rework external references in Tkinter docs #27838 bpo-42560: simplify/merge architecture info in Tkinter docs #27839 bpo-42560: reorganize Tkinter docs modules section for clarity #27840 bpo-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']

[hpmason]

Online python Tkinter documentation (https://docs.python.org/3/library/tkinter.html) lacks many features. The main part I find lacking is documentation on methods, as many of them either aren't listed in the documentation and/or take *args as the only parameter, rather than defined parameters.

Not sure how in-depth docs from effbot were, but those are not currently available.

Existing documentation in the source code (https://github.com/python/cpython/blob/3.9/Lib/tkinter/__init__.py) seems to be a good start to adding to the online documentation.

[E-Paine]

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]

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]

@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]

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]

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]

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]

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]

Here are my broad suggestions for improvement (each of these would turn into a separate PR). Thoughts for/against each?

1. '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)

2. 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)

3. Architecture (was recently added). Merge in (and improve) material from how Tk and Tkinter are related, drop Tix from here

4. 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.

5. '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]

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]

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.

2. 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?).

3. 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.

4. 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)?