From 9f8709b396a8684d0279b6f4abe9c991d9605569 Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Sun, 16 Dec 2018 06:40:43 +0900
Subject: [PATCH] doc: Add policy reference

Partially Implements: blueprint neutron-policy-in-code

Change-Id: I906646c5e0975b7de14135aa610b4ff18f5a0fe4
---
 .gitignore                                 |  1 +
 doc/source/conf.py                         |  7 ++++
 doc/source/configuration/index.rst         | 37 ++++++++++++++--------
 doc/source/configuration/policy-sample.rst | 16 ++++++++++
 doc/source/configuration/policy.rst        |  9 ++++++
 5 files changed, 56 insertions(+), 14 deletions(-)
 create mode 100644 doc/source/configuration/policy-sample.rst
 create mode 100644 doc/source/configuration/policy.rst

diff --git a/.gitignore b/.gitignore
index ceaae435d..a6f182eb4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ covhtml/
 dist/
 doc/build
 doc/source/_static/config_samples/*.sample
+doc/source/_static/*.policy.yaml.sample
 doc/source/contributor/api/
 etc/*.sample
 *.DS_Store
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a49308eb6..c12c6c153 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -48,6 +48,8 @@ extensions = ['sphinxcontrib.apidoc',
               'sphinx.ext.todo',
               'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxext',
+              'oslo_policy.sphinxpolicygen',
               'openstackdocstheme',]
 
 try:
@@ -290,3 +292,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-fwaas'
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 7edd2a247..988ea7e7d 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,32 +1,41 @@
 .. _configuring:
 
-=============================
-Neutron Configuration Options
-=============================
+=================================
+Neutron FWaaS Configuration Guide
+=================================
 
 This section provides a list of all possible options for each
 configuration file.
 
-Configuration Reference
------------------------
+Configuration
+-------------
 
-Neutron uses the following configuration files for its various services.
+Neutron FWaaS uses the following configuration files for its various services.
 
 .. toctree::
-   :glob:
    :maxdepth: 1
 
-   *
+   neutron_fwaas
+   fwaas_driver
 
-Sample Configuration Files
---------------------------
-
-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.
+The following are sample configuration files for Neutron FWaaS and utilities.
+These are generated from code and reflect the current state of code
+in the neutron-fwaas repository.
 
 .. toctree::
    :glob:
    :maxdepth: 1
 
    samples/*
+
+Policy
+------
+
+Neutron FWaaS, 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>
diff --git a/doc/source/configuration/policy-sample.rst b/doc/source/configuration/policy-sample.rst
new file mode 100644
index 000000000..d5c9cd537
--- /dev/null
+++ b/doc/source/configuration/policy-sample.rst
@@ -0,0 +1,16 @@
+================================
+Sample Neutron FWaaS Policy File
+================================
+
+The following is a sample neutron-fwaas policy file for adaptation and use.
+
+The sample policy can also be viewed in :download:`file form
+</_static/neutron-fwaas.policy.yaml.sample>`.
+
+.. important::
+
+   The sample policy file is auto-generated from neutron-fwaas when this
+   documentation is built. You must ensure your version of neutron-fwaas
+   matches the version of this documentation.
+
+.. literalinclude:: /_static/neutron-fwaas.policy.yaml.sample
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 000000000..697aa96d7
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,9 @@
+======================
+neutron-fwaas policies
+======================
+
+The following is an overview of all available policies in neutron-fwaas.
+For a sample configuration file, refer to :doc:`/configuration/policy-sample`.
+
+.. show-policy::
+      :config-file: etc/oslo-policy-generator/policy.conf