docs: Add config documentation to operator's section

This PS adds configuration documentation that includes
a literalinclude of the config file as well as some
information on each of the cache config options as
these are important on performance.

Change-Id: I3b06012b8843b7bfbd46307f81397172a41d3675

deckhand/conf/config.py

@@ -112,6 +112,7 @@ def list_opts():
             ks_loading.get_auth_plugin_conf_options('password') +
             ks_loading.get_auth_plugin_conf_options('v3password')
         ),
+        engine_group: engine_opts,
         barbican_group: (
             barbican_opts +
             ks_loading.get_session_conf_options() +

doc/source/conf.py

@@ -40,6 +40,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinxcontrib.apidoc',
+    'oslo_config.sphinxconfiggen',
     'oslo_policy.sphinxpolicygen',
     # NOTE(fmontei): This is here so that readthedocs can publish releasenotes
     # as well as documentation on the same domain and to do that we use a
@@ -59,6 +60,10 @@ apidoc_excluded_paths = [
 ]
 apidoc_separate_modules = True
 
+# oslo_config.sphinxconfiggen options
+config_generator_config_file = '../../etc/deckhand/config-generator.conf'
+sample_config_basename = '_static/deckhand'
+
 # oslo_policy.sphinxpolicygen options
 policy_generator_config_file = '../../etc/deckhand/policy-generator.conf'
 sample_policy_basename = '_static/deckhand'

doc/source/operators/configuration.rst

@@ -0,0 +1,49 @@
+..
+  Copyright 2018 AT&T Intellectual Property.  All other rights reserved.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+
+Deckhand Configuration
+======================
+
+Cache Configuration
+-------------------
+
+Deckhand currently uses 3 different caches for the following use cases:
+
+* Caching rendered documents (see :ref:`rendering`) for faster future look-ups
+* Caching Barbican secret payloads
+* Caching ``jsonschema`` results for quickly resolving deeply nested dictionary
+  data
+
+All 3 caches are implemented in memory.
+
+Please reference the configuration groups below to enable or customize the
+timeout for each cache:
+
+* ``[barbican]``
+* ``[engine]``
+* ``[jsonschema]``
+
+Sample Configuration File
+-------------------------
+
+The following is a sample Deckhand config file for adaptation and use. It is
+auto-generated from Deckhand when this documentation is built, so
+if you are having issues with an option, please compare your version of
+Deckhand with the version of this documentation.
+
+The sample configuration can also be viewed in `file form <_static/deckhand.conf.sample>`_.
+
+.. literalinclude:: ../_static/deckhand.conf.sample

doc/source/operators/index.rst

@@ -22,6 +22,7 @@ Operator's Guide
 
    api_ref
    api_client
+   configuration
    exceptions
 
 Indices and tables