Documentation for static contexts

4 files changed, 62 insertions, 1 deletions

diff --git a/doc/cmd.rst b/doc/cmd.rst
index 908b2ee9..0d1a05b5 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -69,7 +69,7 @@ control, and can provide options that other invocation techniques (like test
 runner plugins) may not offer. See :ref:`config` for more details.
 
 
-.. _cmd_execution:
+.. _cmd_run:
 
 Execution
 ---------
@@ -118,6 +118,10 @@ configuration file for all options.
 .. _gevent: http://www.gevent.org/
 .. _eventlet: http://eventlet.net/
 
+You can specify a :ref:`static context <contexts>` for a coverage run with
+``--context``.  This can be any label you want, and will be recorded with the
+data.  See :ref:`contexts` for more information.
+
 By default, coverage.py does not measure code installed with the Python
 interpreter, for example, the standard library. If you want to measure that
 code as well as your own, add the ``-L`` (or ``--pylib``) flag.
diff --git a/doc/config.rst b/doc/config.rst
index 666a1321..b8117a43 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -132,6 +132,11 @@ Before version 4.2, this option only accepted a single string.
 
 .. versionadded:: 4.0
 
+``context`` (string): the static context to record for this coverage run. See
+:ref:`contexts` for more information
+
+.. versionadded:: 5.0
+
 ``data_file`` (string, default ".coverage"): the name of the data file to use
 for storing or reporting coverage. This value can include a path to another
 directory.
diff --git a/doc/contexts.rst b/doc/contexts.rst
new file mode 100644
index 00000000..c1d4a173
--- /dev/null
+++ b/doc/contexts.rst
@@ -0,0 +1,51 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+.. _contexts:
+
+====================
+Measurement Contexts
+====================
+
+.. :history: 20180921T085400, new for 5.0
+
+.. versionadded:: 5.0
+
+Coverage.py measures whether code was run, but it can also record the context
+in which it was run.  This can provide more information to help you understand
+the behavior of your tests.
+
+There are two kinds of context: static and dynamic.  Static contexts are fixed
+for an entire run, and are set explicitly with an option.
+
+Dynamic contexts are coming soon.
+
+
+Static contexts
+---------------
+
+A static context is set by an option when you run coverage.py.  The value is
+fixed for the duration of a run.  They can be any text you like, for example,
+"python3" or "with_numpy".  The context is recorded with the data.
+
+When you :ref:`combine multiple data files <cmd_combining>` together, they can
+have differing contexts.  All of the information is retained, so that the
+different contexts are correctly recorded in the combined file.
+
+A static context is specified with the ``--context=CONTEXT`` option to
+:ref:`coverage run <cmd_run>`.
+
+
+Dynamic contexts
+----------------
+
+Not implemented yet.
+
+
+Context reporting
+-----------------
+
+There is currently no support for using contexts during reporting.  I'm
+interested to `hear your ideas`__ for what would be useful.
+
+__  https://nedbatchelder.com/site/aboutned.html
diff --git a/doc/index.rst b/doc/index.rst
index 0a795011..149eba07 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -206,6 +206,7 @@ More information
     excluding
     branch
     subprocess
+    contexts
     api
     howitworks
     plugins