diff --git a/.gitignore b/.gitignore
index c307e065e3..4f5c1cfef7 100644
--- a/.gitignore
+++ b/.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
diff --git a/doc/source/conf.py b/doc/source/conf.py
index b12725136a..b4b8cf01d5 100644
--- a/doc/source/conf.py
+++ b/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.
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 57eb317981..6a8970d0b2 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -9,3 +9,4 @@ Configuring Heat
    clients.rst
    config-options.rst
    logs.rst
+   sample_policy.rst
diff --git a/doc/source/configuration/sample_policy.rst b/doc/source/configuration/sample_policy.rst
new file mode 100644
index 0000000000..78814abe82
--- /dev/null
+++ b/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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b6dd616d60..1874570cec 100644
--- a/doc/source/index.rst
+++ b/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::
diff --git a/etc/heat/heat-policy-generator.conf b/etc/heat/heat-policy-generator.conf
index 6d11632acf..bd05e3469f 100644
--- a/etc/heat/heat-policy-generator.conf
+++ b/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
diff --git a/releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml b/releasenotes/notes/policy-in-code-124372f6cdb0a497.yaml
new file mode 100644
index 0000000000..5f4700ec3a
--- /dev/null
+++ b/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.