classification
Title: TKinter docs page does not provide actual documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: duplicate
Dependencies: Superseder: Improve Tkinter Documentation
View: 42560
Assigned To: docs@python Nosy List: arkevorkhat, docs@python, epaine, steven.daprano, zach.ware
Priority: normal Keywords:

Created on 2021-06-22 08:42 by arkevorkhat, last changed 2021-06-22 20:04 by zach.ware. This issue is now closed.

Messages (5)
msg396313 - (view) Author: Chris Trent (arkevorkhat) Date: 2021-06-22 08:42
The documentation pages for the tkinter module are not actually documentation. They are tutorials, which belong on the wiki. "Documentation" is not documentation if it does not provide at bare minimum a structured list of all names exposed by the module's public interface. 

Python's official docs should be the sole authoritative source for full, complete, useful documentation of everything one could need to know about a module, but instead, We're forced to go to 3rd party sites of dubious provenance and questionable accuracy, instead of being able to just go to the source, and find a page to, I don't know, find out what kinds of panels we have to work with.
msg396314 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-06-22 09:09
Are you referring to this?

https://docs.python.org/3/library/tkinter.html

I acknowledge that there are legitimate criticism of the tkinter docs, and its weaknesses, but you overstate your case.

- Tutorials are documentation, they just aren't *reference* documentation; there are other kinds of documentation, such as Quick Start Guides, How Tos, tutorials, FAQs, man pages, doc strings, etc.

- Tutorials don't necessarily belong on a wiki.

- A structured list of names in the public interface is certainly nice to have, but it shouldn't be taken as the one feature that defines documentation.

- That our docs "... should be the sole authoritative source" is nice to aspire to, but probably not practical in the case of tkinter.

Having said all that, please do submit patches with concrete improvements. Don't feel that you must completely redesign the entire tkinter docs. Incremental improvements are welcome as well.

"3rd party sites of dubious provenance and questionable accuracy"

I don't think that tkdocs.com is any more dubious or questionable than anything we could write; and the tcl/tk documentation at tcl.tk is the one source of truth for tcl/tk. Tkinter is just a third-party interface to it.
msg396321 - (view) Author: Chris Trent (arkevorkhat) Date: 2021-06-22 11:21
To put it bluntly, having me submit patches to that section of the docs is just about the last thing you want. I know precious little about TKinter, which is precisely why I'm calling for something more than a half-assed tutorial.

Regarding using the TCL/TK docs, not happening. I don't have the time nor patience to learn a dead scripting language just to read docs, if I wanted to do that, I'd learn Javascript.
msg396355 - (view) Author: E. Paine (epaine) * Date: 2021-06-22 17:52
> full, complete, useful documentation of everything

Please see msg384022 on why I'm personally against such changes. I was working on 'translating' the Tk man pages into something (hopefully) understandable by tkinter users (as reference documentation), however lost steam after completing only ~2/3 of the canvas methods (due to the size of such a project).

> at bare minimum a structured list of all names exposed by the module's public interface

Like Steven, I think this would probably be a helpful change, however, this is of limited use without an accompanying description.
msg396360 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2021-06-22 20:04
I'm closing this as a duplicate of bpo-42560 (and probably several others).

Chris: in short, we know the Tkinter docs are incomplete and we welcome improvements to them, but it costs just as much to say "I don't have the time to spend on this" as it does to say "you have to make this easier for me for free" :).

As far as using the official Tk docs for Tkinter: their documentation is fairly comprehensive and easily translatable, because Tkinter as a translation layer tries to be as thin as possible.  You don't have to know Tcl to use their documentation beyond some very basic syntax.  To add full documentation of Tkinter, we would basically have to copy all of Tk's documentation.  At that point, it feels pretty pointless to do so when we can just point there in the first place (as we already do).
History
Date User Action Args
2021-06-22 20:04:48zach.waresetstatus: open -> closed

superseder: Improve Tkinter Documentation

nosy: + zach.ware
messages: + msg396360
resolution: duplicate
stage: resolved
2021-06-22 17:52:31epainesetnosy: + epaine
messages: + msg396355
2021-06-22 11:21:58arkevorkhatsetmessages: + msg396321
2021-06-22 09:09:07steven.dapranosettype: behavior -> enhancement

messages: + msg396314
nosy: + steven.daprano
2021-06-22 08:55:21arkevorkhatsettype: behavior
2021-06-22 08:42:57arkevorkhatcreate