[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

> 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!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

miss-islington  added the comment:


New changeset e4795103025aeef295a8c5f75cc7c33801f93a24 by Miss Islington (bot) 
in branch '3.10':
bpo-42560: simplify/merge architecture info in Tkinter docs (GH-27839)
https://github.com/python/cpython/commit/e4795103025aeef295a8c5f75cc7c33801f93a24


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26372
pull_request: https://github.com/python/cpython/pull/27920

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset e41912c6348362489d2514565a70782591f23902 by Mark Roseman in 
branch 'main':
bpo-42560: simplify/merge architecture info in Tkinter docs (GH-27839)
https://github.com/python/cpython/commit/e41912c6348362489d2514565a70782591f23902


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

miss-islington  added the comment:


New changeset 8351df6e3652a41ffc720066a68b666bbef1df67 by Miss Islington (bot) 
in branch '3.10':
bpo-42560: add warning to Tkinter docs about outdated pre-8.5 documentation 
online (GH-27836)
https://github.com/python/cpython/commit/8351df6e3652a41ffc720066a68b666bbef1df67


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26371
pull_request: https://github.com/python/cpython/pull/27915

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset 1eb451031a64b4f28d737ee7f394252ae9a76118 by Mark Roseman in 
branch 'main':
bpo-42560: add warning to Tkinter docs about outdated pre-8.5 documentation 
online (GH-27836)
https://github.com/python/cpython/commit/1eb451031a64b4f28d737ee7f394252ae9a76118


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26367
pull_request: https://github.com/python/cpython/pull/27911

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26368
pull_request: https://github.com/python/cpython/pull/27912

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset 08830a4f75553682e8d1ea6cdabd4c3472c59e28 by Mark Roseman in 
branch 'main':
bpo-42560: rewrite of Tkinter docs "life preserver" (GH-27842)
https://github.com/python/cpython/commit/08830a4f75553682e8d1ea6cdabd4c3472c59e28


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset 986750be5c7914f4b0120f5627fe848dcced103b by Miss Islington (bot) 
in branch '3.9':
bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840) 
(GH-27895)
https://github.com/python/cpython/commit/986750be5c7914f4b0120f5627fe848dcced103b


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset c579f0ba62974b90f348e50088e4c036e281f45e by Łukasz Langa in 
branch '3.9':
[3.9] bpo-42560: rework external references in Tkinter docs (GH-27838) 
(GH-27896)
https://github.com/python/cpython/commit/c579f0ba62974b90f348e50088e4c036e281f45e


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset 8e90f15ac88c66ddb7b084bb5780a126d35168af by Łukasz Langa in 
branch '3.10':
[3.10] bpo-42560: rework external references in Tkinter docs (GH-27838) 
(GH-27893)
https://github.com/python/cpython/commit/8e90f15ac88c66ddb7b084bb5780a126d35168af


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

miss-islington  added the comment:


New changeset 4d1e74f352d8bf70b726b373e19fd21274899d8e by Miss Islington (bot) 
in branch '3.10':
bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840)
https://github.com/python/cpython/commit/4d1e74f352d8bf70b726b373e19fd21274899d8e


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset e74cf8667d7d73e6cacd5d0aedcecbd20e711d6a by Miss Islington (bot) 
in branch '3.9':
bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState 
(GH-27835) (GH-27892)
https://github.com/python/cpython/commit/e74cf8667d7d73e6cacd5d0aedcecbd20e711d6a


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

miss-islington  added the comment:


New changeset 61ecd3e593e05c3d84adf5640458a01f8550aa74 by Miss Islington (bot) 
in branch '3.10':
bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState 
(GH-27835)
https://github.com/python/cpython/commit/61ecd3e593e05c3d84adf5640458a01f8550aa74


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Change by Łukasz Langa :


--
pull_requests: +26351
pull_request: https://github.com/python/cpython/pull/27896

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26349
pull_request: https://github.com/python/cpython/pull/27894

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset d5dbe8bca792350f4997c027535e0ca498abd1bb by Mark Roseman in 
branch 'main':
 bpo-42560: reorganize Tkinter docs modules section for clarity (GH-27840)
https://github.com/python/cpython/commit/d5dbe8bca792350f4997c027535e0ca498abd1bb


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26350
pull_request: https://github.com/python/cpython/pull/27895

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Change by Łukasz Langa :


--
pull_requests: +26348
pull_request: https://github.com/python/cpython/pull/27893

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +26347
pull_request: https://github.com/python/cpython/pull/27892

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 12.0 -> 13.0
pull_requests: +26346
pull_request: https://github.com/python/cpython/pull/27891

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset 141c7a4fce8def67baa9d24f542c105b8502893e by Mark Roseman in 
branch 'main':
bpo-42560: tweaks to intro of Tkinter docs- add macOS, drop ActiveState 
(GH-27835)
https://github.com/python/cpython/commit/141c7a4fce8def67baa9d24f542c105b8502893e


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:


New changeset d1049d1d6b43296d4db1aa8668aa4ca807bf7adb by Mark Roseman in 
branch 'main':
bpo-42560: rework external references in Tkinter docs (GH-27838)
https://github.com/python/cpython/commit/d1049d1d6b43296d4db1aa8668aa4ca807bf7adb


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26306
pull_request: https://github.com/python/cpython/pull/27842

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26304
pull_request: https://github.com/python/cpython/pull/27840

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26303
pull_request: https://github.com/python/cpython/pull/27839

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26302
pull_request: https://github.com/python/cpython/pull/27838

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26300
pull_request: https://github.com/python/cpython/pull/27836

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
pull_requests: +26299
pull_request: https://github.com/python/cpython/pull/27835

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

> In particular, you added OS-specific info

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.

> Did you exactly copy the tk manual wordings or rewrite in your own words?

All of the text was originally copied from the man pages. I have done a 
reasonable amount of rewording, reformatting and elaborating.

> Do you intend to contribute what you wrote?

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Richard Sheridan]

Change by Richard Sheridan :


--
nosy: +Richard Sheridan

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Łukasz Langa]

Łukasz Langa  added the comment:

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 GH-27717. 
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.

[^1]: https://sembr.org/

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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'd like to see improved tkinter docs within a year.

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?

* In particular, you added OS-specific info.  It seems to be mostly absent from 
*tkinter* doc and not knowing those facts has caused grief.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

> I don't see the tcl/tk versions as an issue

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

> I would like a complete, in some sense, internal reference, which we would be 
> able to correct and further improve

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

> My 'biggest' idea is that we should document tk and ttk widgets together.

That does sound like a very good idea, so long as we make it obvious which 
module to find the specific widget in.

> someone posted a link to a site with distribution versus tcl/tk information

https://pkgs.org/download/tk

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Terry J. Reedy]

Terry J. Reedy  added the comment:

> 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, 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' 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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

Here's a very rough work-in-progress snapshot:
https://github.com/roseman/cpython/blob/tkinter-docs-snapshot-20210815/Doc/library/tkinter.rst

This includes:

1. Changes I'd mentioned to the intro, external resources, modules, architecture

2. Rewrite of the 'life preserver' mini-tutorial section using a very different 
approach.

3. A start on the reference section (replacing the random bits that were there 
with a categorized, but detail-free list of classes and common methods).

Anyone have any big picture thoughts at this point?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

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.

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

--
components: +Tkinter
versions: +Python 3.11

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mason Ginter]

Mason Ginter  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Simão Afonso]

Change by Simão Afonso :


--
nosy: +simao.afonso

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Change by Mark Roseman :


--
nosy: +lukasz.langa, terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mark Roseman]

Mark Roseman  added the comment:

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.

--
nosy: +markroseman

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[FredInChina]

FredInChina  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

> 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 issue37149 - he will also handle any copyright claims, etc. that may 
arise that meant we couldn't host it on docs.python.org).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[FredInChina]

FredInChina  added the comment:

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](https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/index.html) 
after his premature death; yet, some important example files were lost.

We now see [effbot.org](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?

--
nosy: +ReblochonMasque

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

@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?)

--
nosy: +effbot

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mason Ginter]

Mason Ginter  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[E. Paine]

E. Paine  added the comment:

See issue34154. 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/2020145627/http://effbot.org/

--
nosy: +epaine, serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Roundup Robot]

Change by Roundup Robot :


--
keywords: +patch
nosy: +python-dev
nosy_count: 2.0 -> 3.0
pull_requests: +22557
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/23689

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue42560] Improve Tkinter Documentation

[Mason Ginter]

New submission from Mason Ginter :

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.

--
assignee: docs@python
components: Documentation
messages: 382437
nosy: docs@python, mason2
priority: normal
severity: normal
status: open
title: Improve Tkinter Documentation
type: enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com