Add policy documentation and sample file [10/10]

This patch adds documentation and sample
file for default policy in code feature.

Change-Id: I597971a19ec61a1bf8c991b2712ec7644b2e2693
Partial-Implements: blueprint policy-in-code

doc/source/conf.py

@@ -55,12 +55,18 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.graphviz',
               'openstackdocstheme',
               'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxext',
+              'oslo_policy.sphinxpolicygen',
               ]
 
 config_generator_config_file = (
     '../../etc/oslo-config-generator/manila.conf')
 sample_config_basename = '_static/manila'
 
+policy_generator_config_file = (
+    '../../etc/manila/manila-policy-generator.conf')
+sample_policy_basename = '_static/manila'
+
 # openstackdocstheme options
 repository_name = 'openstack/manila'
 bug_project = 'manila'

doc/source/configuration/shared-file-systems/samples/index.rst

@@ -5,7 +5,10 @@ Shared File Systems service sample configuration files
 All the files in this section can be found in ``/etc/manila``.
 
 .. toctree::
+   :maxdepth: 1
 
    manila.conf.rst
    api-paste.ini.rst
    rootwrap.conf.rst
+   policy.rst
+   sample_policy.rst

doc/source/configuration/shared-file-systems/samples/policy.rst

@@ -0,0 +1,11 @@
+====================
+Policy configuration
+====================
+
+Configuration
+~~~~~~~~~~~~~
+
+The following is an overview of all available policies in Manila.
+
+.. show-policy::
+   :config-file: etc/manila/manila-policy-generator.conf

doc/source/configuration/shared-file-systems/samples/sample_policy.rst

@@ -0,0 +1,16 @@
+====================
+Manila Sample Policy
+====================
+
+The following is a sample Manila 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.
+It is here to help explain which policy operations protect specific Manila API,
+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. For
+instance, if you want to change the default value of "share:create", you only
+need to keep this single rule in your policy config
+file (**/etc/manila/policy.json**).
+
+.. literalinclude:: ../../../_static/manila.policy.yaml.sample
+   :language: ini

releasenotes/notes/add-policy-in-code-c31a24ee045d8d21.yaml

@@ -0,0 +1,13 @@
+---
+features:
+  - Default Role Based Access Control (RBAC) policies for all the Manila
+    APIs have moved into code from the auxiliary ``policy.json`` file.
+upgrade:
+  - Removed the default ``policy.json`` file.
+  - Operators need not maintain the ``policy.json`` file if they were not
+    overriding default manila policies.
+  - If Operators need to override certain RBAC policies, they can do so by
+    creating a JSON formatted file named ``policy.json`` and populate it
+    with the necessary overrides. This file must be placed in the config
+    directory. The default RBAC policies are documented in the configuration
+    reference alongside other sample configuration files.