New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve Tkinter Documentation #86726
Comments
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. |
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/ |
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 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)? |
@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?) |
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?
|
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). |
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. |
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. |
Here are my broad suggestions for improvement (each of these would turn into a separate PR). Thoughts for/against each?
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.
|
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. |
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.
|
Here's a very rough work-in-progress snapshot: This includes:
Anyone have any big picture thoughts at this point? |
Yes. For years, I have wanted major changes in out tkinter docs, but making them myself has never become a top priority for me over working directly on IDLE. The latter has been hampered by the inadequate tkinter docs. Fortunately, I have learned to interpret the online tk docs. But I would be happy work with you, Mark, to make something better. My perspective is that of an competent but occasionally user who cannot keep all of tkinter in my head and needs a good reference that does not currently exist. (I am currently working on two other writing projects, but one should be done in a few days. So I should look at your proposals within a week. I already reviewed and critiqued Mason's PR.) I would like a complete, in some some sense, internal reference, which would would be able to correct ad further improve. Complete means everything in the Shipman 8.5 references, but somewhat rearranged and more compact. Current references both external and internal, are variously obsolete, incomplete, and buggy. The latter two apply to our internal ttk doc. All external references suffer from being out of pydev control. I don't see the tcl/tk versions as an issue. First, the 3.x *tkinter* docs should document the features available in the 3.x version of the tkinter module. It could mention that it should best be used with the most recent tcl/tk 8.6 possible. Second, the Centos is about the only *nix distribution not having 8.6 available. On another thread where the question of using something new in 8.6 came up, someone posted a link to a site with distribution versus tcl/tk information. Unfortunately, I cannot find it. The 8.6.z releases mostly add bugfixes. The new-in-8.6 features listed on https://www.tcl.tk/software/tcltk/8.6.html should be in all or most all of 8.6.z releases. My 'biggest' idea is that we should document tk and ttk widgets together. I don't think we should continue to treat ttk as just an optional, and by implication, 'advanced' add-on. Each entry should be labelled tk, tk&ttk, or ttk. Or perhaps there should be 3 subsections so labelled. The ttk doc only has widget entries for ttk (only). Perhaps the authors felt that full entries for 'tk&ttk' widgets would be mostly redundant with docs for the tk versions. I agree, and propose entries that cover both. We should expand on what the ttk doc does in separately documenting options common to more than one widget. I would like to add 1) a table (matrix) of common option versus widget, with marks indicating which option can be used with which widget, and 2) links from each widget doc to the blocks of common widgets it uses. The initial chapters of Shipman are mostly about possible values for some of the options. These belong together in the 'Options' subsection. |
My main concern was when Tcl/Tk has a major new release with new kwargs. If MacOS was shipped with one version and Windows another, I suspect we would have to hold back an update to the docs. I am slightly less concerned now, because so far there are no new kwargs in the 8.7 highlights: https://www.tcl.tk/software/tcltk/8.7.html
Despite being more relaxed about the version issue above, my other major concern is the size of such a project. I started working on some reference documentation I named “tkinter-docs” (https://github.com/E-Paine/tkinter-docs / https://tkinter-docs.readthedocs.io/en/latest/widgets/canvas.html) but as you can see I haven’t worked on it since mid-May (I simply lost steam given the number of hours I’d have to invest to finish it). My thinking is that an open-source documentation would be much easier to maintain going forward (rather being up to a single person to keep up-to-date) without filling Serhiy’s inbox with *a lot* of inevitable docs fixes. IMO, such documentation (regardless of a community to help) would still require a large amount of dedication from a single person to be checking and merging patches. Another thing I think we would need to work out is how we respect the Tk licence’s requirement for attribution while allowing the PSF to relicense the docs as they please (I ‘m assuming that any work we produce would be based heavily enough on the Tk man pages to require the attribution). With tkinter-docs, this was easy enough as I could just include the full Tk license on a somewhat out-of-the-way page. Since the PSF would (probably) want to relicense the entire docs rather than just whatever modifications we’ve made, we may need legal advice or written exemption from the TCT (is there anyone more knowledgeable on the subject that we can nosy?).
That does sound like a very good idea, so long as we make it obvious which module to find the specific widget in.
|
It seems premature to worry about 8.7.0, as it might still be years away. 8.7.0a1 was 4 years ago. 8.6.0 spent 5 years in beta. https://sourceforge.net/projects/tcl/files/Tcl/. I don't think that license should be an issue. Tkinter, as well as our distribution of tcl/tk binaries and the Perl and Ruby tk wrappings, must be allowed by the tcl/tk license. At least by implication, we must be allowed to document the licensed wrapper and its usage from Python. The tkinter-docs listing of widget options is close to what I want to see*, except that I want to separately document shared options, as in the ttk doc. To the extent that I would prefer your versions, you have already done a big chunk of the work for that. Did you exactly copy the tk manual wordings or rewrite in your own words? Do you intend to contribute what you wrote?
|
I would most definitely echo the concern about the massive size of such a project as well as future maintainability. I don't know anyone who would be able to do such a thing on a volunteer basis, and I think it would be highly unlikely that anyone would step up to pay someone to do it. I imagine we all agree that we would love to have such a complete reference, but I have a hard time seeing how it's even remotely feasible. As the effort supporting Tcl/Tk core development is fairly small, and most of the people involved are far more interested in the Tcl side of things rather than Tk, the odds of huge changes on the Tk front are small, beyond keeping it working, fixing bugs, and the odd little isolated burst of new stuff once in a while. Based on previous history with that community, I think you can safely assume any licensing issues won't be an impediment to whatever needs to be done on this end, though I'm sure there are details to sort out. |
Mark, it's great to see you work on the documentation again. I would like you invite you to produce a number of smaller PRs, just like you did with #71904. Those tend to be much easier to include even as we are discussing larger-scale evolution of the documentation. In particular, your cpython forks contains a number of commits, some tiny, some large. Taken in its entirety it will be hard to review because diffs aren't well suited for free-flowing text when semantic newlines aren't used 1. Reworking the tutorial seems like it could go in a separate PR. Same for updating literature to current versions, and so on. Footnotes |
Łukasz, I've got a bunch of individual branches for each of those sections. What I posted the link to was a merge of all of them just for overview purposes, but the PR's will be created from the individual branches. I can start creating those now or wait a bit, whatever is easiest workflow-wise. |
I also deemed this very useful information. The issue is that it is not documented in the man pages and so those values are pulled straight from the source code. We would need to decide whether we keep such information in our docs, which is subject to change without warning.
All of the text was originally copied from the man pages. I have done a reasonable amount of rewording, reformatting and elaborating.
If we conclude a complete doc is the way to go, I would finish documenting the canvas widget, make relevant reformatting changes (such as moving common widget options) and then open a PR. |
Łukasz, thank you very much for your help with getting these changes merged in! I hope others will chime in with suggestions and/or edits to the newer or substantially revised sections. There is most definitely lots of room for improvement. One specific request... does anyone have solid recommendations for other resources (including books, paid video courses, etc.) that extensively cover Tkinter and use current best practices (grid, ttk, etc.)? This would be for the "see also" section. While I think the two free tutorial/reference resources on tkdocs.com make the most sense, I'm a bit queasy about the self-promotion optics of also highlighting Modern Tkinter as prominently as it is now in the books section. That still leaves the "handy reference" section to deal with, which currently consists of a mish-mash of material. When I have a chance, I'll work on a PR with a list of classes and common methods (but not arguments or explanations) as suggested before. While the pieces that were already merged in were probably low on the controversy scale, it's still unclear what the right way forward is with the actual reference part and I expect some more discussion on that. |
Would like to throw an idea out for feedback regarding the API reference. I've done some preliminary work auto-generating documentation via widget introspection. It's missing a lot, has many bugs, but is far enough along to give a sense of what this approach could offer. Temporary snapshot is at https://tkdocs.com/tmp-pyref/ (you may need to force-refresh if your browser cached the site's stylesheet). Note that generating .rst files this way shouldn't be much of a stretch so as to fully integrate into the official Python docs. Thoughts? |
Is it possible to make non-widget specific methods more obvious (the first one that caught my eye was bind_class)? I'm thinking something like using italic with a key at the top noting that is what it means. I like the 'aka' thing, though. Thanks Mark! |
Just a note, that an (updated) version of the auto-generated API reference has been "officially" added to TkDocs ... see https://tkdocs.com/pyref/ Few more things I'd like to do with it in the short term, but it's a decent starting point. Let me know if you have further suggestions. |
Since #23689 was not active for 2 years, and it simply copied docstrings to the documentation, yesterday I started to work on an alternative PR which copies from the Tk docs. Docstrings are less detailed and may be outdated, as they are based on the old Tk docs. It will take several days to create an initial version. |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: