bpo-39452: rewrite and expand __main__.rst

Doc/library/__main__.rst

@@ -329,11 +329,18 @@ status code 0, indicating success:
 
 Note that importing ``__main__`` doesn't cause any issues with unintentionally
 running top-level code meant for script use which is put in the
-``if __name__ == "__main__"`` block of ``start.py``. It's because this code
-has already executed at the start of the program and the module is already
-fully loaded when ``namely.py`` imports ``__main__``.
-
-The Python REPL is one example of a "top-level environment", so anything
+``if __name__ == "__main__"`` block of ``start.py``. Why does this work?
+
+Python inserts an empty ``__main__`` module in :attr:`sys.modules` at
+interpreter startup, and populates it by running top-level code. In our example
+this is the ``start.py`` file which runs line by line and imports ``namely``.
+In turn, ``namely.py`` imports ``__main__`` (which is ``start.py``). That's an
+import cycle! Fortunately, since the partially populated ``__main__``
+module is present in :attr:`sys.modules`, Python passes that to ``namely.py``.
+See :ref:`Special considerations for __main__ <import-dunder-main>` in the
+import system's reference for details on how this works.
+
+The Python REPL is another example of a "top-level environment", so anything
 defined in the REPL becomes part of the ``__main__`` scope::
 
     >>> import namely

Doc/reference/import.rst

@@ -975,6 +975,8 @@ should expose ``XXX.YYY.ZZZ`` as a usable expression, but .moduleY is
 not a valid expression.
 
 
+.. _import-dunder-main:
+
 Special considerations for __main__
 ===================================