Docs for new dynamic context techniques

3 files changed, 22 insertions, 5 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 3b884772..286ace8a 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -16,8 +16,15 @@ Change history for Coverage.py
 Unreleased
 ----------
 
-- Dynamic contexts can now be determined by third-party code in a plugin.
-  Thanks, Justas Sadzevičius.
+- Dynamic contexts can now be set two new ways, both thanks to Justas
+  Sadzevičius.
+
+  - A plugin can implement a ``dynamic_context`` method to check frames for
+    whether a new context should be started.  See
+    :ref:`dynamic_context_plugins` for more details.
+
+  - Another tool (such as a test runner) can use the new
+    :meth:`Coverage.switch_context` method to explicitly change the context.
 
 - The ``dynamic_context = test_function`` setting now works with Python 2
   old-style classes, though it only reports the method name, not the class it
diff --git a/coverage/control.py b/coverage/control.py
index ace3d8bf..76467257 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -487,7 +487,9 @@ class Coverage(object):
         """Switch to a new dynamic context.
 
         `new_context` is a string to use as the context label
-        for collected data.
+        for collected data.  If a :ref:`static context <static_contexts>` is in
+        use, the static and dynamic context labels will be joined together with
+        a pipe character.
 
         Coverage collection must be started already.
 
diff --git a/doc/contexts.rst b/doc/contexts.rst
index 121bd491..e3974ea2 100644
--- a/doc/contexts.rst
+++ b/doc/contexts.rst
@@ -11,6 +11,8 @@ Measurement contexts
 
 .. versionadded:: 5.0
 
+.. module:: coverage
+
 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.
@@ -19,6 +21,7 @@ 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
 change over the course of a single run.
 
+.. _static_contexts:
 
 Static contexts
 ---------------
@@ -36,6 +39,8 @@ A static context is specified with the ``--context=CONTEXT`` option to
 the configuration file.
 
 
+.. _dynamic_contexts:
+
 Dynamic contexts
 ----------------
 
@@ -45,12 +50,15 @@ context tracking.  As execution proceeds, the dynamic context changes
 to record the context of execution.  Separate data is recorded for each
 context, so that it can be analyzed later.
 
-There are two ways to enable dynamic contexts:
+There are three ways to enable dynamic contexts:
 
 * you can set the ``[run] dynamic_context`` option in your .coveragerc file, or
 
 * you can enable a :ref:`dynamic context switcher <dynamic_context_plugins>`
-  plugin.
+  plugin, or
+
+* another tool (such as a test runner) can call the
+  :meth:`Coverage.switch_context` method to set the context explicitly.
 
 The ``[run] dynamic_context`` setting has only one option now.  Set it to
 ``test_function`` to start a new dynamic context for every test function::