Include sample policy file in documentation

Since we're moving all policy into code and documenting it there we
should generate those docs automatically, so they are less likely to
be out-of-date.

Change-Id: If00cd3bcc654a45944c0bc8b3f146c75bd970f9a
partially-implements: blueprint policy-docs

.gitignore

@@ -36,3 +36,5 @@ keystone/locale/*/LC_MESSAGES/*.mo
 releasenotes/build
 # sample config included in docs
 doc/source/_static/keystone.conf.sample
+# sample policy file included in docs
+doc/source/_static/keystone.policy.yaml.sample

doc/source/conf.py

@@ -51,6 +51,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.coverage',
               'sphinx.ext.viewcode',
               'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxpolicygen',
               'oslosphinx',
               'ext.support_matrix',
               ]
@@ -58,6 +59,9 @@ extensions = ['sphinx.ext.autodoc',
 config_generator_config_file = '../../config-generator/keystone.conf'
 sample_config_basename = '_static/keystone'
 
+policy_generator_config_file = '../../etc/keystone-policy-generator.conf'
+sample_policy_basename = '_static/keystone'
+
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/index.rst

@@ -102,13 +102,14 @@ Developers Documentation
    devref/http-api
    devref/services
 
-Sample Configuration File
+Sample Files
-=========================
+============
 
 .. toctree::
     :maxdepth: 1
 
     sample_config
+    sample_policy
 
 Man Pages
 =========

doc/source/sample_policy.rst

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