Skip to content

Windows Launcher docs use incorrect version in examples #101294

Closed

Description

@cringti

Documentation

The "Python Launcher for Windows" section, specifically the "Getting Started" "From a Script" section, uses hard-coded versions when describing shebang behavior, but uses the macro-defined "version" when describing the output. The specific source file with the issue is Doc/using/windows.rst.

As a result, the generated docs say confusing things like "Assuming you have Python 3.7 installed, try changing the first line to #! python3.7 and you should find the Python 3.11 version information printed."

In this case, python "3.7" is hard-coded in the .rst source (which is fine), but "3.11" is generated from a macro, and will therefore vary from release to release.

The docs should either always use the version macro for examples like this, or never use it.

Note that this is just one case I stumbled on. Casually reviewing similar "version" macro usage finds related issues, so a general review for usage of the "version" macro would be useful.

Activity

  1. OTheDev commented on Feb 12, 2023

    @OTheDev
    Contributor

    As a result, the generated docs say confusing things like "Assuming you have Python 3.7 installed, try changing the first line to #! python3.7 and you should find the Python 3.11 version information printed."

    Thanks! Looks like someone might have seen your post and submitted a fix #101385.

    I did a simple grep on main for |version| and it looks like it only appears in /Doc/using/windows.rst. There are only 6 instances of |version| and they all read okay for me.

    Can you point me to the additional examples you are referring to? Maybe I've missed something. Thanks!

  2. cringti commented on Mar 27, 2023

    @cringti
    Author

    Sorry for the slow reply. Your grep turned up the 6 references of |version|, so that's the list. None are necessarily errors, but I thought them worth review by "someone who knows more about the python roadmap than me"... which is just about anybody. 😛

    For example, there's a blind statement that "Python |version| supports Windows 8.1 and newer." Maybe that's still true for current releases, maybe not (link).

    I don't know well enough to recommend any further changes, so we can close this ticket (thanks for the fix, @socal-nerdtastic!).

  3. OTheDev commented on Mar 29, 2023

    @OTheDev
    Contributor

    Thanks @cringti

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions