Merge "Add sample config and policy to documentation"

.gitignore

@@ -80,3 +80,6 @@ releasenotes/build
 
 # Files created by API build
 api-ref/build/
+
+# Files created by doc build
+doc/source/_static

doc/source/conf.py

@@ -22,9 +22,21 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     # 'sphinx.ext.intersphinx',
-    'openstackdocstheme'
+    'openstackdocstheme',
+    'oslo_config.sphinxext',
+    'oslo_config.sphinxconfiggen',
+    'oslo_policy.sphinxext',
+    'oslo_policy.sphinxpolicygen',
 ]
 
+config_generator_config_file = [
+    ('../../etc/oslo-config-generator/barbican.conf',
+     '_static/barbican'),
+]
+
+policy_generator_config_file = '../../etc/oslo-config-generator/policy.conf'
+sample_policy_basename = '_static/barbican'
+
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable

doc/source/configuration/config.rst

@@ -0,0 +1,8 @@
+.. _barbican.conf:
+
+-------------
+barbican.conf
+-------------
+
+.. show-options::
+      :config-file: etc/oslo-config-generator/barbican.conf

doc/source/configuration/index.rst

@@ -9,3 +9,5 @@ Setting up Barbican
    noauth.rst
    audit.rst
    plugin_backends.rst
+   config.rst
+   policy.rst

doc/source/configuration/policy.rst

@@ -0,0 +1,14 @@
+.. _barbican-policy-generator.conf:
+
+====================
+Policy configuration
+====================
+
+Configuration
+~~~~~~~~~~~~~
+
+The following is an overview of all available policies in Barbican. For a sample
+configuration file.
+
+.. show-policy::
+      :config-file: ../../etc/oslo-config-generator/policy.conf

doc/source/index.rst

@@ -27,6 +27,15 @@ API.
 
    api/index.rst
 
+Sample Files
+============
+
+.. toctree::
+      :maxdepth: 1
+
+   sample_config
+   sample_policy
+
 
 
 Indices and tables

doc/source/sample_config.rst

@@ -0,0 +1,8 @@
+==================================
+Barbican Sample Configuration File
+==================================
+
+Use the ``barbican.conf`` file to configure most Key Manager service
+options:
+
+.. literalinclude:: _static/barbican.conf.sample

doc/source/sample_policy.rst

@@ -0,0 +1,15 @@
+======================
+Barbican Sample Policy
+======================
+
+The following is a sample Barbican policy file that has been auto-generated
+from default policy values in code. If you're using the default policies, then
+the maintenance of this file is not necessary, and it should not be copied into
+a deployment. Doing so will result in duplicate policy definitions. It is here
+to help explain which policy operations protect specific Barbican APIs, but it
+is not suggested to copy and paste into a deployment unless you're planning on
+providing a different policy for an operation that is not the default.
+
+The sample policy file can also be viewed in `file form <_static/barbican.policy.yaml.sample>`_.
+
+.. literalinclude:: _static/barbican.policy.yaml.sample