classification
Title: Overhaul of Doc/library/__main__.rst
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cameron, docs@python, iritkatriel, jack__d
Priority: normal Keywords: patch

Created on 2021-06-23 03:29 by jack__d, last changed 2021-06-23 19:25 by jack__d. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26867 closed jack__d, 2021-06-23 03:35
PR 26883 merged jack__d, 2021-06-23 19:25
Messages (4)
msg396380 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-23 03:29
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.
msg396387 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-23 08:46
Hi Jack,

I'm not sure it's necessary to create a new issue for "Overhaul of Doc/library/__main__.rst" when we already have Issue39452 to "Improve the __main__ module documentation" and Issue24632 to "Improve documentation about __main__.py".  What we really need to is close all but one of them as duplicates and consolidate the work. Also, the people who are on the nosy lists of the previous issues will not necessarily see the discussion you opened on this one if you won't alert them to it.

Have you looked at the open PR on issue39452?  I think there may be some overlap with what you did here (but I didn't check in any detail).
msg396410 - (view) Author: Jack DeVries (jack__d) * Date: 2021-06-23 11:57
@iritkatriel, ok, I will close this issue, close PR26867, and move the work I have over there. I probably can merge in and build upon the work from the contributor on bpo-39452.
msg396412 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-23 12:11
That's a good plan!
History
Date User Action Args
2021-06-23 19:25:40jack__dsetpull_requests: + pull_request25461
2021-06-23 12:11:26iritkatrielsetmessages: + msg396412
2021-06-23 11:57:29jack__dsetstatus: open -> closed
stage: patch review -> resolved
2021-06-23 11:57:21jack__dsetmessages: + msg396410
2021-06-23 08:46:07iritkatrielsetnosy: + iritkatriel
messages: + msg396387
2021-06-23 08:33:52iritkatrielsetnosy: + cameron
2021-06-23 03:35:28jack__dsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25442
2021-06-23 03:29:41jack__dcreate