Add Docs for the policy in code work

Change-Id: Ie097e5b48f5e42c9c30efdb2d6d9a6aa9e65387c

designate/common/policies/base.py

@@ -18,10 +18,11 @@ from oslo_policy import policy
 
 RULE_ADMIN_OR_OWNER = 'rule:admin_or_owner'
 RULE_ADMIN = 'rule:admin'
-RULE_ZONE_PRIMARY_OR_ADMIN = "('PRIMARY':%(zone_type)s and rule:admin_or_owner)\
-                            OR ('SECONDARY':%(zone_type)s AND is_admin:True)"
-RULE_ZONE_TRANSFER = "rule:admin_or_owner or tenant:%(target_tenant_id)s \
-                            or None:%(target_tenant_id)s"
+RULE_ZONE_PRIMARY_OR_ADMIN = \
+    "('PRIMARY':%(zone_type)s and rule:admin_or_owner) "\
+    "OR ('SECONDARY':%(zone_type)s AND is_admin:True)"
+RULE_ZONE_TRANSFER = "rule:admin_or_owner OR tenant:%(target_tenant_id)s " \
+                     "OR None:%(target_tenant_id)s"
 RULE_ANY = "@"
 
 rules = [

doc/source/admin/index.rst

@@ -17,8 +17,10 @@ Contents:
    blacklists
    quotas
    designate-manage
+   policy
    notifications
    production-guidelines
    upgrades/index
    troubleshooting
-   
+   samples/index
+

doc/source/admin/policy.rst

@@ -0,0 +1,9 @@
+=============
+Sample Policy
+=============
+
+The following is an overview of all available policies in Designate. For a
+sample configuration file, refer to :doc:`samples/policy-yaml`.
+
+.. show-policy::
+   :config-file: ../../etc/designate/designate-policy-generator.conf

doc/source/admin/samples/index.rst

@@ -0,0 +1,11 @@
+==========================
+Sample configuration files
+==========================
+
+Configuration files can alter how designate behaves at runtime and by default
+are located in ``/etc/designate/``. Links to sample configuration files can be
+found below:
+
+.. toctree::
+
+   policy-yaml.rst

doc/source/admin/samples/policy-yaml.rst

@@ -0,0 +1,8 @@
+===========
+policy.yaml
+===========
+
+Use the ``policy.yaml`` file to define additional access controls that apply to
+the DNS service:
+
+.. literalinclude:: ../../_static/designate.policy.yaml.sample

doc/source/conf.py

@@ -33,7 +33,9 @@ extensions = ['sphinx.ext.autodoc',
               'ext.support_matrix',
               'ext.custom_css',
               'openstackdocstheme',
-              'oslo_config.sphinxconfiggen']
+              'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxpolicygen',
+              'oslo_policy.sphinxext']
 
 # openstackdocstheme options
 repository_name = 'openstack/designate'
@@ -44,6 +46,9 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 config_generator_config_file = '../../etc/designate/designate-config-generator.conf'
 sample_config_basename = '_static/designate'
 
+policy_generator_config_file = '../../etc/designate/designate-policy-generator.conf'
+sample_policy_basename = '_static/designate'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

releasenotes/notes/policy-in-code-8d3f4f89e2ede50f.yaml

@@ -0,0 +1,17 @@
+---
+features:
+  - |
+    Designate now support policy in code, which means if users don't want to
+    modify any of policy rules, they can remove or comment all of rules in
+    policy file or even not deploy it at all. Because from now, Designate keeps
+    all default policies under `designate/common/policies` module.
+    Users can modify/generate `policy.yaml` file which will override policy
+    rules in code if those rules show in `policy.yaml` file.
+    Users also still use `policy.json` file but oslo team recommend that we
+    should use the newer YAML format instead.
+
+other:
+  - |
+    Default `policy.json` file is now removed as Designate now generate the
+    default policies from code. Please be aware that when using that file in
+    your environment.

tox.ini

@@ -38,6 +38,7 @@ commands =
   ostestr '{posargs}'
 
 [testenv:docs]
+basepython = python2.7
 commands = rm -rf doc/build
            python setup.py build_sphinx