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

@@ -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',
               ]

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

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

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