Merge "Render policy in documentation"

doc/source/conf.py

@@ -17,7 +17,6 @@ import os
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
-
 sys.path.insert(0, ROOT)
 sys.path.insert(0, BASE_DIR)
 
@@ -44,8 +43,12 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinxcontrib.pecanwsme.rest',
     'openstackdocstheme',
+    'oslo_policy.sphinxpolicygen'
 ]
 
+policy_generator_config_file = '../../etc/panko/panko-policy-generator.conf'
+sample_policy_basename = '_static/panko'
+
 wsme_protocols = ['restjson', 'restxml']
 
 todo_include_todos = True

doc/source/configuration/sample_policy.rst

@@ -0,0 +1,15 @@
+===================
+Panko Sample Policy
+===================
+
+The following is a sample panko 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 panko 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/panko.policy.yaml.sample>`_.
+
+.. literalinclude:: _static/panko.policy.yaml.sample

doc/source/index.rst

@@ -38,6 +38,14 @@ Overview
 
 .. update index
 
+Sample Configuration Files
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration/sample_policy
+
 Indices and tables
 ==================