From a3a5470538e63b67c206238d2dba2e977c875bd2 Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Thu, 17 Jan 2019 23:59:49 +0900
Subject: [PATCH] doc: Add policy reference

Partially Implements: blueprint neutron-policy-in-code

Change-Id: Iad80250e52e2347b0f6844ebaeb5a51cd314daf0
---
 .gitignore                                 |  1 +
 doc/source/conf.py                         |  7 +++++
 doc/source/configuration/index.rst         | 30 ++++++++++++++--------
 doc/source/configuration/policy-sample.rst | 17 ++++++++++++
 doc/source/configuration/policy.rst        | 10 ++++++++
 etc/README.txt                             | 15 ++++++-----
 6 files changed, 63 insertions(+), 17 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 df6c3eb7..82244a30 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
 etc/*.sample
 *.DS_Store
 *.pyc
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a0d93b4e..7c3d88cc 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,6 +25,8 @@ extensions = [
     'openstackdocstheme',
     'oslo_config.sphinxext',
     'oslo_config.sphinxconfiggen',
+    'oslo_policy.sphinxext',
+    'oslo_policy.sphinxpolicygen',
 ]
 
 # openstackdocstheme options
@@ -101,3 +103,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-dynamic-routing'
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index b5616f4f..e6b5506b 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,24 +1,20 @@
-=====================
-Configuration Options
-=====================
+===================
+Configuration Guide
+===================
+
+Configuration
+-------------
 
 This section provides a list of all possible options for each
 configuration file.
 
-Configuration Reference
------------------------
-
 neutron-dynamic-routing uses the following configuration files for its
 various services.
 
 .. toctree::
-   :glob:
    :maxdepth: 1
 
-   *
-
-Sample Configuration Files
---------------------------
+   bgp_dragent
 
 The following are sample configuration files for neutron-dynamic-routing.
 These are generated from code and reflect the current state of code
@@ -29,3 +25,15 @@ in the neutron-dynamic-routing repository.
    :maxdepth: 1
 
    samples/*
+
+Policy
+------
+
+neutron-dynamic-routing, 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 00000000..c6d20c3b
--- /dev/null
+++ b/doc/source/configuration/policy-sample.rst
@@ -0,0 +1,17 @@
+==========================================
+Sample neutron-dynamic-routing Policy File
+==========================================
+
+The following is a sample neutron-dynamic-routing policy file for adaptation
+and use.
+
+The sample policy can also be viewed in :download:`file form
+</_static/neutron-dynamic-routing.policy.yaml.sample>`.
+
+.. important::
+
+   The sample policy file is auto-generated from neutron-dynamic-routing when
+   this documentation is built. You must ensure your version of
+   neutron-dynamic-routing matches the version of this documentation.
+
+.. literalinclude:: /_static/neutron-dynamic-routing.policy.yaml.sample
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 00000000..3c9627f5
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,10 @@
+================================
+neutron-dynamic-routing policies
+================================
+
+The following is an overview of all available policies in
+neutron-dynamic-routing. For a sample configuration file,
+refer to :doc:`/configuration/policy-sample`.
+
+.. show-policy::
+      :config-file: etc/oslo-policy-generator/policy.conf
diff --git a/etc/README.txt b/etc/README.txt
index adf61672..58b20003 100644
--- a/etc/README.txt
+++ b/etc/README.txt
@@ -1,9 +1,12 @@
-To generate the sample neutron-dynamic-routing configuration files, run the
-following command from the top level of the neutron-dynamic-routing directory:
+To generate the sample neutron-dynamic-routing configuration files and the
+sample policy file, run the following commands respectively from the top level
+of the neutron-dynamic-routing directory:
 
-tox -e genconfig
+  tox -e genconfig
+  tox -e genpolicy
 
-If a 'tox' environment is unavailable, then you can run the following script
-instead to generate the configuration files:
+If a 'tox' environment is unavailable, then you can run the following commands
+instead to generate the configuration files and the policy file:
 
-./tools/generate_config_file_samples.sh
+  ./tools/generate_config_file_samples.sh
+  oslopolicy-sample-generator --config-file=etc/oslo-policy-generator/policy.conf