Document the [paths] section in the config file.

Author: nedbat

CHANGES.txt

@@ -5,6 +5,11 @@ Change history for Coverage.py
 Version 3.5.1
 -------------
 
+- When combining data files from parallel runs, you can now instruct coverage
+  about which directories are equivalent on different machines.  A ``[paths]``
+  section in the configuration file lists paths that are to be considered
+  equivalent.
+
 - for-else constructs are understood better, and don't cause erroneous partial
   branch warnings.  Fixes `issue 122`_.
 

doc/cmd.rst

@@ -11,6 +11,7 @@ Coverage command line usage
 :history: 20091127T200700, changes for 3.2
 :history: 20100223T200600, changes for 3.3
 :history: 20100725T211700, updated for 3.4
+:history: 20110827T212500, updated for 3.5.1, combining aliases
 
 .. highlight:: console
 
@@ -139,6 +140,11 @@ data file::
 
     $ coverage combine
 
+If the different machines run your code from different places in their file
+systems, coverage won't know how to combine the data.  You can tell coverage
+how the different locations correlate with a ``[paths]`` section in your
+configuration file.  See :ref:`config_paths` for details.
+
 
 .. _cmd_reporting:
 

doc/config.rst

@@ -8,6 +8,7 @@ Configuration files
 :history: 20100725T211700, updated for 3.4.
 :history: 20100824T092900, added ``precision``.
 :history: 20110604T184400, updated for 3.5.
+:history: 20110827T212700, updated for 3.5.1
 
 
 Coverage.py options can be specified in a configuration file.  This makes it
@@ -103,6 +104,33 @@ measure during execution.  See :ref:`source` for details.
 Try this if you get seemingly impossible results.
 
 
+.. _config_paths:
+
+[paths]
+-------
+
+The entries in this section are lists of file paths that should be
+considered equivalent when combining data from different machines::
+
+    [paths]
+    source =
+        src/
+        /jenkins/build/*/src
+        c:\myproj\src
+
+The names of the entries are ignored, you may choose any name that
+you like.  The value is a lists of strings.  When combining data
+with the ``combine`` command, two file paths will be combined
+if they start with paths from the same list.
+
+The first value must be an actual file path on the machine where
+the reporting will happen, so that source code can be found.
+The other values can be file patterns to match against the paths
+of collected data.
+
+See :ref:`cmd_combining` for more information.
+
+
 [report]
 --------