This repo, Akuli/tkinter-tutorial, typeshed

[Akuli]

I have written some tkinter stuff to Akuli/tkinter-tutorial. Occasionally someone stars it, but I haven't done anything to it in a couple years.

For detailed documentation (as in https://github.com/rdbende/tkinter-docs/blob/main/docs/tk/tk.html ), I think writing a Python-specific copy of Tk man pages wouldn't be great. It would be a huge amount of effort to write, and it would get outdated easily. In fact, tkinter has plenty of docstrings that are just like this, and I never trust them. We have a couple options:

• Refer to Tk manual pages and explain how to read them. This is what I have tried to do
• Convert Tk docs to Python docs with a script. This way nothing should get outdated if there is a new option to some widget, for example.
• Refer to the tkinter stubs in typeshed and explain how to read them. I wrote/rewrote most of them, and they can be quite useful if you are wondering what options a widget has and what type they should be, for example. Here's ttk.Button stubs, to give you an idea of what the stubs are like: https://github.com/python/typeshed/blob/master/stdlib/tkinter/ttk.pyi#L36

What do you think?

[rdbende]

Thank you for your time and thoughts!

I think manually converting the tcl man page to python is really not worth. That’s why I stopped making documentation pages, it was so boring that I started to tweak css instead XD

I don't prefer the first option tbh, because although the tcl tk man page is very detailed, it's difficult to find the necessary info between the option database names and others. Nor does it tell us which feature is implemented in tkinter and which is not (e.g. options from wm_attributes, or fontchooser, busy, windowingsystem, scaling and so on). this may not be hard for an experienced tkinter user who may be familiar with the source code, (especially if it's bookmarked for easy access lol), but for someone else it can be difficult, even with this help.

The second idea is what I really like. Automating would be awesome, although I’ve never done a web scraping project before. I’m not afraid I should update the documentation daily, but it would still be a lot easier to do it all with a single script.

I definitely find it useful to write down the types. It's often difficult to guess that a given widget accepts an empty string, or None, or just 0 for the default. Or when the text widget also accepts a float as an index. Another example, in the case of event_generate kwargs, I had to guess from the error messages which keyword accepts what type, because there is no documentation about it anywhere (and then for some reason I didn't find the description of the tk man page). I started write the types in the wm_attributes options, I want to continue this way.

[Akuli]

a web scraping project

On Debian-based linux distros, you can sudo apt install tk-doc and do things like man 3tk label to look at the Tk manuals. They are the same manuals as online, and I think this would be overall a better approach than relying on what's online. We could probably find a way to download the manuals for specific versions of Tk, and compare them to add things like "New in Tk 8.6."

Another example, in the case of event_generate kwargs, I had to guess from the error messages which keyword accepts what type, because there is no documentation about it anywhere

See event generate window event ?option value option value ...? in event(3tk). It says "see EVENT FIELDS below", and if you scroll down to "EVENT FIELDS", there's your docs :)