From 99016b67fc8e3187e7b8642df70562eb7d8f362e Mon Sep 17 00:00:00 2001
From: Lance Bragstad <lbragstad@gmail.com>
Date: Tue, 28 Nov 2017 15:49:05 +0000
Subject: [PATCH] Render policy in documentation

This is the final bit to implementing the policy goal for Panko.
This just ensures the policies registered in code are actually
rendered in documentation and up-to-date.

Change-Id: I5c97263b84695c0a83dc82782d2f8861dca8ced5
---
 doc/source/conf.py                         |  5 ++++-
 doc/source/configuration/sample_policy.rst | 15 +++++++++++++++
 doc/source/index.rst                       |  8 ++++++++
 3 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/configuration/sample_policy.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 3538298f..35c947bd 100644
--- a/doc/source/conf.py
+++ b/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
diff --git a/doc/source/configuration/sample_policy.rst b/doc/source/configuration/sample_policy.rst
new file mode 100644
index 00000000..0a2db68a
--- /dev/null
+++ b/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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c0526185..e287afca 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -38,6 +38,14 @@ Overview
 
 .. update index
 
+Sample Configuration Files
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration/sample_policy
+
 Indices and tables
 ==================