doc: Add policy reference

Partially Implements: blueprint neutron-policy-in-code

Change-Id: Ie0d1293d9352b29627801ed6103aa1e9ce8915dd

.gitignore

@@ -7,6 +7,7 @@ covhtml/
 dist/
 doc/build
 doc/source/_static/config_samples/*.sample
+doc/source/_static/*.policy.yaml.sample
 etc/*.sample
 *.DS_Store
 *.pyc

doc/source/conf.py

@@ -50,6 +50,8 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxext',
+              'oslo_policy.sphinxpolicygen',
               'openstackdocstheme',]
 
 todo_include_todos = True
@@ -263,3 +265,8 @@ config_generator_config_file = [
     _get_config_generator_config_definition(conf)
     for conf in _config_generator_config_files
 ]
+
+# -- Options for oslo_policy.sphinxpolicygen ---------------------------------
+
+policy_generator_config_file = '../../etc/oslo-policy-generator/policy.conf'
+sample_policy_basename = '_static/neutron-vpnaas'

doc/source/configuration/index.rst

@@ -1,30 +1,39 @@
-=====================
+===================
-Configuration Options
+Configuration Guide
-=====================
+===================
+
+Configuration
+-------------
 
 This section provides a list of all possible options for each
 configuration file.
 
-Configuration Reference
+Neutron VPNaaS uses the following configuration files for its various services.
------------------------
-
-Neutron uses the following configuration files for its various services.
 
 .. toctree::
-   :glob:
    :maxdepth: 1
 
-   *
+   neutron_vpnaas
+   l3_agent
 
-Sample Configuration Files
+The following are sample configuration files for Neutron VPNaaS services and
---------------------------
-
-The following are sample configuration files for all Neutron services and
 utilities. These are generated from code and reflect the current state of code
-in the Neutron repository.
+in the neutron-vpnaas repository.
 
 .. toctree::
    :glob:
    :maxdepth: 1
 
    samples/*
+
+Policy
+------
+
+Neutron VPNaaS, like most OpenStack projects, uses a policy language to
+restrict permissions on REST API actions.
+
+.. toctree::
+   :maxdepth: 1
+
+   Policy Reference <policy>
+   Sample Policy File <policy-sample>

doc/source/configuration/policy-sample.rst

@@ -0,0 +1,16 @@
+=================================
+Sample Neutron VPNaaS Policy File
+=================================
+
+The following is a sample neutron-vpnaas policy file for adaptation and use.
+
+The sample policy can also be viewed in :download:`file form
+</_static/neutron-vpnaas.policy.yaml.sample>`.
+
+.. important::
+
+   The sample policy file is auto-generated from neutron-vpnaas when this
+   documentation is built. You must ensure your version of neutron-vpnaas
+   matches the version of this documentation.
+
+.. literalinclude:: /_static/neutron-vpnaas.policy.yaml.sample

doc/source/configuration/policy.rst

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