[Doc] explain parametrization conventions (#404)

.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

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
 --------------------------