Skip to content
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

bpo-42560: rewrite of Tkinter docs "life preserver" #27842

Merged
merged 3 commits into from
Aug 23, 2021

Conversation

roseman
Copy link
Contributor

@roseman roseman commented Aug 19, 2021

This PR is effectively a complete rewrite and reorganization of the existing 'Life Preserver' section, and as such it's more useful to compare them in their entirety rather than trying to parse line-by-line diffs. Realistically, I don't think it would be useful to try to break this up into smaller PR's.

The goals, as stated in the new intro:

  • quick orientation to what Tkinter app looks like
  • identify foundational concepts
  • explain structure of Tkinter wrapper
  • how to identify classes, methods, etc. you'll need
  • how to find detailed documentation elsewhere

To summarize the changes:

  • drop credits section

  • replace specific reference to man page sections, old Ousterhout book, Tkinter source code with pointer back to previous list of external references

  • hello world:

    • replaced class-based (so much shorter, more direct)
    • now uses ttk and grid
    • added line-by-line walkthrough
  • important tk(inter) concepts

    • new section
    • some of this was muddled in the previous Tcl-oriented sections, but most not there
  • understanding how tkinter wraps tcl/tk

    • made shorter, more descriptive, less indirect/illustrative explanation of concepts
    • less walking through actual Tcl syntax
    • emphasizes important points of difference
  • how do I ... / what option...

    • this was previously dispersed across several sections, now more task-oriented
    • assumption is that external documentation will be used, and knowing the right term to search for is key
    • remind about introspection facilities for methods and objects, and also identifying those unique to a particular widget
  • navigating tcl/tk reference manual

    • solves the problem of given name of method, where to go find it in man pages?
    • explains that while in tkinter everything is a method, in Tcl/Tk some are widget-specific methods, others are toplevel commands (e.g. grid)
    • points to pages for common options and methods
    • describes where to find docs on methods with compound names, e.g. "winfo_..."
    • notes gotcha that some things that look like methods for a specific widget actually don't operate on the widget

https://bugs.python.org/issue42560

@ambv ambv added skip news needs backport to 3.9 only security fixes needs backport to 3.10 only security fixes labels Aug 23, 2021
@ambv ambv merged commit 08830a4 into python:main Aug 23, 2021
@miss-islington
Copy link
Contributor

Thanks @roseman for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry @roseman and @ambv, I had trouble checking out the 3.10 backport branch.
Please backport using cherry_picker on command line.
cherry_picker 08830a4f75553682e8d1ea6cdabd4c3472c59e28 3.10

@bedevere-bot
Copy link

GH-27911 is a backport of this pull request to the 3.9 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.9 only security fixes label Aug 23, 2021
@ambv ambv added needs backport to 3.9 only security fixes and removed needs backport to 3.10 only security fixes labels Aug 23, 2021
@miss-islington
Copy link
Contributor

Thanks @roseman for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 23, 2021
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit 08830a4)

Co-authored-by: Mark Roseman <mark@markroseman.com>
@ambv ambv added the needs backport to 3.10 only security fixes label Aug 23, 2021
@miss-islington
Copy link
Contributor

Thanks @roseman for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

@bedevere-bot
Copy link

GH-27912 is a backport of this pull request to the 3.10 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 only security fixes label Aug 23, 2021
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 23, 2021
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit 08830a4)

Co-authored-by: Mark Roseman <mark@markroseman.com>
@hpmason hpmason mannequin mentioned this pull request Nov 3, 2023
@ZeroIntensity ZeroIntensity removed the needs backport to 3.9 only security fixes label Feb 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants