From b03e8151341f16ce7317569c86b51253a8c3635f Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Thu, 3 Aug 2017 16:34:25 +0100
Subject: [PATCH] doc: Start using oslo_policy.sphinxext

Providing a sample policy file is all well and good, but it's not
exactly designed for readability on the web. Make use of the 'sphinxext'
module built into oslo.policy to do this.

Change-Id: I6cceeca7edcacb762daa1f22f2138e2d2334b3a2
---
 doc/source/conf.py                         |  1 +
 doc/source/configuration/policy.rst        |  9 +++++++++
 doc/source/configuration/sample-policy.rst | 16 ++++++++++------
 doc/source/index.rst                       |  5 +++--
 4 files changed, 23 insertions(+), 8 deletions(-)
 create mode 100644 doc/source/configuration/policy.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index a45e0f4500b5..d6c5928f8c99 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -42,6 +42,7 @@ extensions = ['sphinx.ext.autodoc',
               'oslo_config.sphinxconfiggen',
               'oslo_config.sphinxext',
               'oslo_policy.sphinxpolicygen',
+              'oslo_policy.sphinxext',
               'ext.versioned_notifications',
               'ext.feature_matrix',
               ]
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 000000000000..8fea1406e5c0
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,9 @@
+========
+Policies
+========
+
+The following is an overview of all available policies in Nova.  For a sample
+configuration file, refer to :doc:`/configuration/sample-policy`.
+
+.. show-policy::
+   :config-file: etc/nova/nova-policy-generator.conf
diff --git a/doc/source/configuration/sample-policy.rst b/doc/source/configuration/sample-policy.rst
index acf67dfb626b..0e4b699af792 100644
--- a/doc/source/configuration/sample-policy.rst
+++ b/doc/source/configuration/sample-policy.rst
@@ -1,12 +1,16 @@
-===========
-Nova Policy
-===========
+==================
+Sample Policy File
+==================
 
-The following is a sample nova policy file, autogenerated from nova when this
-documentation is built. To prevent conflicts, ensure your version of nova
-aligns with the version of this documentation.
+The following is a sample nova policy file for adaptation and use.
 
 The sample policy can also be viewed in :download:`file form
 </_static/nova.policy.yaml.sample>`.
 
+.. important::
+
+   The sample policy file is auto-generated from nova when this documentation
+   is built. You must ensure your version of nova matches the version of this
+   documentation.
+
 .. literalinclude:: /_static/nova.policy.yaml.sample
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c7fe6d2b7987..46bae298f7f5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -203,12 +203,13 @@ Configuration
     configuration/config
     configuration/sample-config
 
-Sample Policy file
-------------------
+Policy
+------
 
 .. toctree::
     :maxdepth: 1
 
+    configuration/policy
     configuration/sample-policy
 
 Man Pages