Docs on spec files

mgalloy · Apr 23, 2019 · 98244b9 · 98244b9
1 parent 8c03acb
commit 98244b9
Showing 1 changed file with 30 additions and 2 deletions.
diff --git a/docs/spec.rst b/docs/spec.rst
@@ -4,8 +4,11 @@ Specification files
 
 Specification files provide a specification for each option in a configuration file. This specification allows:
 
-1. The `get` method can automatically return the value as the correct type, including using a default value if an optional value was not given in the configuration file.
-2. The configuration file(s) can be validated against the specification to ensure all required options are provided and no extra options are given.
+1. the ``get`` method to automatically return the value as the correct type
+2. the ``get`` method to return a default value if an optional value was not given in the configuration file
+3. the configuration file(s) to be validated against the specification to ensure all required options are provided and no extra options are given.
+
+For example, a specification file might look like the following:
 
 .. code-block:: text
 
@@ -19,3 +22,28 @@ Specification files provide a specification for each option in a configuration f
   [level1]
   wavelengths   : type=List[float], default=[]
   wavetypes     : type=List[str], default="[1074, 1079, 1083]"
+
+The configuration file that uses this specification might be like:
+
+.. code-block:: text
+
+  [logging]
+  basedir       : /Users/mgalloy/data
+  level         : DEBUG
+  rotate        : NO
+  max_version   : 3
+
+  [level1]
+  wavelengths   : [1074.7, 1079.8, 1083.0]
+
+The possible attributes for an option are listed below.
+
+required
+  whether the option is required; allowed values (case-insensitive) for required are "True", "YES", or "1" and "False", "NO", or "0" for not required 
+type
+  Python type: ``str`` (default), ``int``, ``float``, ``bool``/``boolean`` or ``List[]`` of one of the scalar types i.e., ``List[int]``
+default
+  default value if the option is not specified
+
+
+Specification files for epoch configuration files use only the ``DEFAULT`` section whereas specification files for standard configuration files mirror the same sections as their configuration files.