TKinter docs page does not provide actual documentation

[e8d77446-9adc-4ded-969a-3d587f586dce]

BPO	44485
Nosy	@stevendaprano, @zware, @E-Paine
Superseder	bpo-42560: Improve Tkinter Documentation

^{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: ```python assignee = None closed_at = created_at = labels = ['type-feature', '3.9', 'docs'] title = 'TKinter docs page does not provide actual documentation' updated_at = user = 'https://bugs.python.org/arkevorkhat' ``` bugs.python.org fields: ```python activity = actor = 'zach.ware' assignee = 'docs@python' closed = True closed_date = closer = 'zach.ware' components = ['Documentation'] creation = creator = 'arkevorkhat' dependencies = [] files = [] hgrepos = [] issue_num = 44485 keywords = [] message_count = 5.0 messages = ['396313', '396314', '396321', '396355', '396360'] nosy_count = 5.0 nosy_names = ['steven.daprano', 'docs@python', 'zach.ware', 'epaine', 'arkevorkhat'] pr_nums = [] priority = 'normal' resolution = 'duplicate' stage = 'resolved' status = 'closed' superseder = '42560' type = 'enhancement' url = 'https://bugs.python.org/issue44485' versions = ['Python 3.9'] ```

[e8d77446-9adc-4ded-969a-3d587f586dce]

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.

[stevendaprano]

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.

[e8d77446-9adc-4ded-969a-3d587f586dce]

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.

[919475b3-36a2-4cd7-997c-9c38f05f93c7]

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.

[zware]

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