From 95ae01feb5518faab18f570cd7a627a0d2145529 Mon Sep 17 00:00:00 2001
From: Hal Wine <132412+hwine@users.noreply.github.com>
Date: Thu, 29 Oct 2020 13:39:14 -0700
Subject: [PATCH] [Doc] explain parametrization conventions (#404)

---
 .travis.yml          |  3 ++-
 docs/NewServices.rst | 21 +++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index d80b8e6..da88be8 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -24,4 +24,5 @@ deploy:
     keep_history: true
     local_dir: docs/_build/html/
     on:
-      branch: master
+      ### DO NOT MERGE ###
+      branch: hwine/doc-new-service
diff --git a/docs/NewServices.rst b/docs/NewServices.rst
index 276ce1f..b4481f4 100644
--- a/docs/NewServices.rst
+++ b/docs/NewServices.rst
@@ -65,6 +65,27 @@ Tests for these support files should be included as doc tests whenever
 practical. If possible, the default of executing the module should be to run
 the doc tests.
 
+Conventions for Parametrization
+--------------------------------------------------
+
+One of the enhancements Frost makes to pytest is simplifying the task of getting test specific metadata into the JSON file to simplify downstream processing. To access this feature, you need to follow a few conventions that are unique to Frost.
+
+When you use the ``pytest.mark.parametrize`` function, you supply two key arguments (see the `pytest documentation`_ for more details):
+
+- ``argvalues`` (2nd argument) - an iterable where each item contains information for one execution of the test.
+- ``ids`` (keyword argument) - a iterable where which results in a text string displayed, in addition to the test name, to uniquly identify one execution of the test. Caution: the string value is used for lookup during exemption processing. The mapping must be stable for this to work as expected -- you can not let pytest generate a default value.
+
+For any values you want to appear in the JSON output, ``argvalues`` should supply a dictionary with a unique-to-context key value. To actually insert the key, value pair into the output JSON, you must also specify the key in the global set ``METADATA_KEYS``. Presence of the key in that set is what triggers the frost additions to put the key, value pair into the output JSON.  One way to do that is:
+
+.. code-block:: python
+
+   from conftest import METADATA_KEYS
+
+   METADATA_KEYS.update("key_1", "key_2")
+
+
+.. _pytest documentation: https://docs.pytest.org/en/stable/reference.html#pytest.python.Metafunc.parametrize
+
 Add Service Specific Tests
 --------------------------