[New-bugs-announce] [issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

New submission from Jack DeVries <jdevries3133 at gmail.com>:

I made a proposal on discourse to redraft Doc/library/__main__.rst as it is currently quite terse and there have been a series of bpo's asking for more. See my discourse post:

https://discuss.python.org/t/proposed-overhaul-of-main-py-documentation-doc-library-main-rst/9344
================
There have been many complaints about the shortcoming of the documentation
towards informing users about __main__. Both the popular __name__ == '__main__' construct, and the role of __main__.py in a python module.

bpo-17359
bpo-24632
bpo-38452

I propose a broad overhaul of Doc/library/__main__.rst to address these
shortcomings and to provide a single source of truth on __main__ (in
general!). This is an appropriate place to put this information.
Both the __name__ == '__main__' and fooModule/__main__.py
constructs reasonably fall under the category of “Python Runtime Services,”
because they both control the way that programs run depending on how they are
used (command-line versus import versus running directly).

The new Doc/library/__main__.rst should have a new synopsis of, “CLIs,
import-time behavior, and if __name__ == ‘__main__’”, reflecting its new and
broader focus.

Additionally, the new docs should have the following distinct sections:

    Differentiating between __name__ == ‘__main__’ and __main.__.py
    __main__.py and the -m flag (this is roughly what is there already, although
    it’s not as descriptive as it should be).
    __name__ and the if __name__ == '__main__' construct.

If there is interest, I would be happy to open uptake this work on as soon as there is
consensus around this plan. I’m looking forward to hearing what you think!
================

Anyway, I have a first draft ready. I'm sure there will be plenty of feedback, so let it rip! I will open a GitHub PR and attach it to this bpo in just a moment.

----------
assignee: docs at python
components: Documentation
messages: 396380
nosy: docs at python, jack__d
priority: normal
severity: normal
status: open
title: Overhaul of Doc/library/__main__.rst
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue44494>
_______________________________________