Documentation for static contexts

1 files changed, 51 insertions, 0 deletions

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