Merge "Add sample policy file to documentation"

doc/source/conf.py

@@ -26,6 +26,8 @@ extensions = [
     'reno.sphinxext',
     'oslo_config.sphinxext',
     'oslo_config.sphinxconfiggen',
+    'oslo_policy.sphinxext',
+    'oslo_policy.sphinxpolicygen',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -48,6 +50,9 @@ config_generator_config_file = [
      '_static/karbor'),
 ]
 
+policy_generator_config_file = '../../etc/karbor-policy-generator.conf'
+sample_policy_basename = '_static/karbor'
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 

doc/source/configuration/policy.rst

@@ -0,0 +1,14 @@
+.. _karbor-policy-generator.conf:
+
+====================
+Policy configuration
+====================
+
+Configuration
+~~~~~~~~~~~~~
+
+The following is an overview of all available policies in Karbor. For a sample
+configuration file.
+
+.. show-policy::
+   :config-file: ../../etc/karbor-policy-generator.conf

doc/source/index.rst

@@ -54,6 +54,14 @@ Release Notes
 
    releasenotes
 
+Sample Files
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   sample_policy
+
 Indices and tables
 ==================
 

doc/source/sample_policy.rst

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