[docs] [issue24632] Improve documentation about __main__.py

[Ezio Melotti]

New submission from Ezio Melotti:

__main__.py seems to only be mentioned briefly in a couple of places in the official docs:
1) https://docs.python.org/3/library/__main__.html
2) https://docs.python.org/3/using/cmdline.html#cmdoption-m

The first link only says:
"""For a package, the same effect can be achieved by including a __main__.py module, the contents of which will be executed when the module is run with -m."""

("-m" should actually use :option:`-m` to automatically link to the second URL.)

The second link mentions __main__.py in two sentences:
"""Execute the Python code contained in script, which must be a filesystem path (absolute or relative) referring to either a Python file, a directory containing a __main__.py file, or a zipfile containing a __main__.py file."""

"""If the script name refers to a directory or zipfile, the script name is added to the start of sys.path and the __main__.py file in that location is executed as the __main__ module."""

I think it would be better to expand the first link to state clearly what is __main__.py and what is its purpose.  In addition, the section should clarify a few more things, e.g. when it should be used, what it should contain, if it's ok to have other __main__.py in the subpackages (e.g. test/__main__.py to run the tests with python -m package.test), how it interacts __init__.py (which one is executed first?).
Perhaps it should also get a glossary entry and/or a short mention in the tutorial together with zip imports.

In addition to the two links above, a Google search returns the stackoverflow question "What is __main__.py?" as first result, and a couple more related questions that could/should be answered by our docs.

----------
assignee: docs at python
components: Documentation
messages: 246719
nosy: docs at python, ethan.furman, ezio.melotti, nedbat
priority: normal
severity: normal
stage: needs patch
status: open
title: Improve documentation about __main__.py
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24632>
_______________________________________