[issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

Change by Jack DeVries :


--
pull_requests: +25461
pull_request: https://github.com/python/cpython/pull/26883

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Irit Katriel]

Irit Katriel  added the comment:

That's a good plan!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

Change by Jack DeVries :


--
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

Jack DeVries  added the comment:

@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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Irit Katriel]

Irit Katriel  added the comment:

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).

--
nosy: +iritkatriel

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Irit Katriel]

Change by Irit Katriel :


--
nosy: +cameron

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

Change by Jack DeVries :


--
keywords: +patch
pull_requests: +25442
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/26867

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44494] Overhaul of Doc/library/__main__.rst

[Jack DeVries]

New submission from Jack DeVries :

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@python
components: Documentation
messages: 396380
nosy: docs@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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com