Merge "Include sample policy file in documentation"

.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