[policy in code] part 7 add sample and releasenote

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.
Also add releasenote for ops to aware that Heat is now using
policies in code and their Orchestration service needs to avoid
depends on policy.json file if file not exist, since there is no
such file by default after this patch.
Partially-Implements: bp policy-in-code

Change-Id: I25fc5a110b1fe515918e042f220c23ac9a7e811f

.gitignore

@@ -26,7 +26,10 @@ etc/heat/heat.conf.sample
 heat_integrationtests/requirements.txt
 
 # generated policy file
-etc/heat/policy.json.sample
+etc/heat/policy.yaml.sample
+
+# sample policy file included in docs
+doc/source/_static/heat.policy.yaml.sample
 
 # Files created by releasenotes build
 releasenotes/build

doc/source/conf.py

@@ -78,10 +78,16 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinx.ext.doctest',
               'openstackdocstheme',
+              'oslo_policy.sphinxext',
+              'oslo_policy.sphinxpolicygen',
               'ext.resources',
               'ext.tablefromtext',
               'stevedore.sphinxext']
 
+# policy sample file generation
+policy_generator_config_file = '../../etc/heat/heat-policy-generator.conf'
+sample_policy_basename = '_static/heat'
+
 # openstackdocstheme options
 repository_name = 'openstack/heat'
 bug_project = 'heat'
@@ -180,7 +186,7 @@ html_theme_options = {"sidebar_mode": "toc"}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # Add any paths that contain "extra" files, such as .htaccess or
 # robots.txt.

doc/source/configuration/index.rst

@@ -9,3 +9,4 @@ Configuring Heat
    clients.rst
    config-options.rst
    logs.rst
+   sample_policy.rst

doc/source/configuration/sample_policy.rst

@@ -0,0 +1,18 @@
+==================
+Heat Sample Policy
+==================
+
+The following is a sample heat 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 heat 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.
+
+If you wish build a policy file, you can also use ``tox -e genpolicy`` to
+generate it.
+
+The sample policy file can also be downloaded in `file form <../_static/heat.policy.yaml.sample>`_.
+
+.. literalinclude:: ../_static/heat.policy.yaml.sample

doc/source/index.rst

@@ -113,7 +113,6 @@ API Documentation
 
    .. _`Heat REST API Reference (OpenStack API Complete Reference - Orchestration)`: http://developer.openstack.org/api-ref/orchestration/v1/
 
-
 Code Documentation
 ==================
 .. toctree::

etc/heat/heat-policy-generator.conf

@@ -1,4 +1,3 @@
 [DEFAULT]
-format = json
 namespace = heat
-output_file = etc/heat/policy.json.sample
+output_file = etc/heat/policy.yaml.sample

releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml

@@ -0,0 +1,15 @@
+---
+features:
+  - |
+    Heat now support policy in code, which means if you didn't modify any of
+    policy rules, you won't need to add rules in the `policy.yaml` or
+    `policy.json` file. Because from now, heat keeps all default policies under
+    `heat/policies`. You can still generate and modify a `policy.yaml` file
+    which will override policy rules in code if those rules appear in the
+    `policy.yaml` file.
+upgrade:
+  - |
+    Default policy.json file is now removed as we now generate the default
+    policies in code. Please be aware that when using that file in your
+    environment. You still can generate a `policy.yaml` file if that's required
+    in your environment.