From f2030a2714e5430e7583eb881aaf7737826e2298 Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Sun, 9 Feb 2020 14:59:22 -0500
Subject: [PATCH] Better document the window's gotcha solution in test code

---
 examples/__main__.py        | 14 +++++++++++---
 tests/test_docs_examples.py | 22 +++++++++++++++++-----
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/examples/__main__.py b/examples/__main__.py
index 7cb2506..c3f7add 100644
--- a/examples/__main__.py
+++ b/examples/__main__.py
@@ -1,11 +1,19 @@
 """
-Needed in windows.
-This needs to be the main program as it will be
-called '__mp_main__' by the multiprocessing module
+Needed on Windows.
+
+This module is needed as the program entry point for invocation
+with ``python -m <modulename>``. See the solution from @chrizzFTD
+here:
+
+    https://github.com/goodboy/tractor/pull/61#issuecomment-470053512
 
 """
 if __name__ == '__main__':
     import multiprocessing
     multiprocessing.freeze_support()
+    # ``tests/test_docs_examples.py::test_example`` will copy each
+    # script from this examples directory into a module in a new
+    # temporary dir and name it test_example.py. We import that script
+    # module here and invoke it's ``main()``.
     from . import test_example
     test_example.tractor.run(test_example.main, start_method='spawn')
diff --git a/tests/test_docs_examples.py b/tests/test_docs_examples.py
index c6bce2e..8776372 100644
--- a/tests/test_docs_examples.py
+++ b/tests/test_docs_examples.py
@@ -11,7 +11,9 @@ import shutil
 import pytest
 
 
-def confdir():
+def repodir():
+    """Return the abspath to the repo directory.
+    """
     dirname = os.path.dirname
     dirpath = os.path.abspath(
         dirname(dirname(os.path.realpath(__file__)))
@@ -20,7 +22,9 @@ def confdir():
 
 
 def examples_dir():
-    return os.path.join(confdir(), 'examples')
+    """Return the abspath to the examples directory.
+    """
+    return os.path.join(repodir(), 'examples')
 
 
 @pytest.fixture
@@ -32,20 +36,21 @@ def run_example_in_subproc(loglevel, testdir, arb_addr):
 
         if platform.system() == 'Windows':
             # on windows we need to create a special __main__.py which will
-            # be executed with ``python -m __main__.py`` on windows..
+            # be executed with ``python -m <modulename>`` on windows..
             shutil.copyfile(
                 os.path.join(examples_dir(), '__main__.py'),
                 os.path.join(str(testdir), '__main__.py')
             )
 
-            # drop the ``if __name__ == '__main__'`` guard
+            # drop the ``if __name__ == '__main__'`` guard from the *NIX
+            # version of each script
             script_code = '\n'.join(script_code.splitlines()[:-4])
             script_file = testdir.makefile('.py', script_code)
 
             # without this, tests hang on windows forever
             kwargs['creationflags'] = subprocess.CREATE_NEW_PROCESS_GROUP
 
-            # run the "libary module" as a script
+            # run the testdir "libary module" as a script
             cmdargs = [
                 sys.executable,
                 '-m',
@@ -78,6 +83,13 @@ def run_example_in_subproc(loglevel, testdir, arb_addr):
     [f for f in os.listdir(examples_dir()) if '__' not in f],
 )
 def test_example(run_example_in_subproc, example_script):
+    """Load and run scripts from this repo's ``examples/`` dir as a user
+    would copy and pasing them into their editor.
+
+    On windows a little more "finessing" is done to make ``multiprocessing`` play nice:
+    we copy the ``__main__.py`` into the test directory and invoke the script as a module
+    with ``python -m test_example``.
+    """
     ex_file = os.path.join(examples_dir(), example_script)
     with open(ex_file, 'r') as ex:
         code = ex.read()