Docs functionally complete for 3.3

1 files changed, 47 insertions, 0 deletions

diff --git a/doc/subprocess.rst b/doc/subprocess.rst
new file mode 100644
index 00000000..d976f692
--- /dev/null
+++ b/doc/subprocess.rst
@@ -0,0 +1,47 @@
+.. _subprocess:
+
+======================
+Measuring subprocesses
+======================
+
+:history: 20100224T201800, new for 3.3.
+
+
+Complex test suites may spawn subprocesses to run tests, either to run them in
+parallel, or because subprocess behavior is an important part of the code under
+test.  Measuring coverage in those subprocesses can be tricky because you have
+to modify the code spawning the process to invoke coverage.py.
+
+There's an easier way to do it: coverage.py includes a function,
+:func:`coverage.process_startup` designed to be invoked when Python starts.  It
+examines the ``COVERAGE_PROCESS_START`` environment variable, and if it is set,
+begins coverage measurement. Its value will be used as the name of the
+:ref:`configuration file <config>` to use.
+
+When using this technique, be sure to set the parallel option to true so that
+multiple coverage.py runs will each write their data to a distinct file.
+
+
+Configuring Python for subprocess coverage
+------------------------------------------
+
+You can configure your Python installation to invoke the ``process_startup``
+function in two ways:
+
+#. Create or append to sitecustomize.py to add these lines::
+
+    import coverage
+    coverage.process_startup()
+
+#. Create a .pth file in your Python installation containing::
+
+    import coverage; coverage.process_startup()
+
+The sitecustomize.py technique is cleaner, but may involve modifying an existing
+sitecustomize.py, since there can be only one.  If there is no sitecustomize.py
+already, you can create it in any directory on the Python path.
+
+The .pth technique seems like a hack, but works, and is documented behavior.
+On the plus side, you can create the file with any name you like so you don't
+have to coordinate with other .pth files.  On the minus side, you have to create
+the file in a system-defined directory, so you may need privileges to write it.