From 55c5139d79ef09869eea1201c736eee8de3ec651 Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Wed, 19 Dec 2018 04:28:15 +0900
Subject: [PATCH] doc: Add policy reference

This is the preparation of migration to DocumendedRuleDefault.

Partially Implements: blueprint neutron-policy-in-code

Change-Id: I1d10f5db43167a04546565545d7d21010d16a808
---
 .gitignore                                  |  1 +
 doc/source/conf.py                          |  7 +++
 doc/source/configuration/config-samples.rst | 25 ++++++++
 doc/source/configuration/config.rst         | 31 ++++++++++
 doc/source/configuration/index.rst          | 65 +++++----------------
 doc/source/configuration/policy-sample.rst  | 16 +++++
 doc/source/configuration/policy.rst         |  9 +++
 7 files changed, 104 insertions(+), 50 deletions(-)
 create mode 100644 doc/source/configuration/config-samples.rst
 create mode 100644 doc/source/configuration/config.rst
 create mode 100644 doc/source/configuration/policy-sample.rst
 create mode 100644 doc/source/configuration/policy.rst

diff --git a/.gitignore b/.gitignore
index 3536e3d92bc..7195937f27e 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
 etc/neutron/plugins/ml2/*.sample
 *.DS_Store
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 7748ad226cd..b57c237ccd9 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -67,6 +67,8 @@ extensions = [
     'support_matrix',
     'oslo_config.sphinxext',
     'oslo_config.sphinxconfiggen',
+    'oslo_policy.sphinxext',
+    'oslo_policy.sphinxpolicygen',
 ]
 
 # openstackdocstheme options
@@ -277,6 +279,11 @@ config_generator_config_file = [
     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'
+
 linkcheck_anchors_ignore = [
     # skip gerrit anchors
     r'\/q\/.*',
diff --git a/doc/source/configuration/config-samples.rst b/doc/source/configuration/config-samples.rst
new file mode 100644
index 00000000000..80a181294c3
--- /dev/null
+++ b/doc/source/configuration/config-samples.rst
@@ -0,0 +1,25 @@
+==========================
+Sample Configuration Files
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   samples/neutron.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   samples/ml2-conf.rst
+   samples/linuxbridge-agent.rst
+   samples/macvtap-agent.rst
+   samples/openvswitch-agent.rst
+   samples/sriov-agent.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   samples/dhcp-agent.rst
+   samples/l3-agent.rst
+   samples/metadata-agent.rst
+   samples/metering-agent.rst
diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst
new file mode 100644
index 00000000000..062a1b722e4
--- /dev/null
+++ b/doc/source/configuration/config.rst
@@ -0,0 +1,31 @@
+=======================
+Configuration Reference
+=======================
+
+This section provides a list of all configuration options for various neutron
+services. These are auto-generated from neutron code when this documentation is
+built. Configuration filenames used below are filenames usually used, but there
+is no restriction on configuration filename in neutron and you can use
+arbitrary file names.
+
+.. toctree::
+   :maxdepth: 1
+
+   neutron.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   ml2-conf.rst
+   linuxbridge-agent.rst
+   macvtap-agent.rst
+   openvswitch-agent.rst
+   sriov-agent.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   dhcp-agent.rst
+   l3-agent.rst
+   metadata-agent.rst
+   metering-agent.rst
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index ef03e3b4668..41984e1eaa7 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,61 +1,26 @@
 .. _configuring:
 
-=============================
-Neutron Configuration Options
-=============================
+===========================
+Neutron Configuration Guide
+===========================
 
-This section provides a list of all configuration options for various neutron
-services. These are auto-generated from neutron code when this documentation is
-built. Configuration filenames used below are filenames usually used, but there
-is no restriction on configuration filename in neutron and you can use
-arbitrary file names.
-
-Configuration Reference
------------------------
+Configuration
+-------------
 
 .. toctree::
    :maxdepth: 1
 
-   neutron.rst
+   config
+   config-samples
+
+Policy
+------
+
+Neutron, like most OpenStack projects, uses a policy language to restrict
+permissions on REST API actions.
 
 .. toctree::
    :maxdepth: 1
 
-   ml2-conf.rst
-   linuxbridge-agent.rst
-   macvtap-agent.rst
-   openvswitch-agent.rst
-   sriov-agent.rst
-
-.. toctree::
-   :maxdepth: 1
-
-   dhcp-agent.rst
-   l3-agent.rst
-   metadata-agent.rst
-   metering-agent.rst
-
-Sample Configuration Files
---------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   samples/neutron.rst
-
-.. toctree::
-   :maxdepth: 1
-
-   samples/ml2-conf.rst
-   samples/linuxbridge-agent.rst
-   samples/macvtap-agent.rst
-   samples/openvswitch-agent.rst
-   samples/sriov-agent.rst
-
-.. toctree::
-   :maxdepth: 1
-
-   samples/dhcp-agent.rst
-   samples/l3-agent.rst
-   samples/metadata-agent.rst
-   samples/metering-agent.rst
+   Policy Reference <policy>
+   policy-sample
diff --git a/doc/source/configuration/policy-sample.rst b/doc/source/configuration/policy-sample.rst
new file mode 100644
index 00000000000..e7a04046def
--- /dev/null
+++ b/doc/source/configuration/policy-sample.rst
@@ -0,0 +1,16 @@
+==================
+Sample Policy File
+==================
+
+The following is a sample neutron policy file for adaptation and use.
+
+The sample policy can also be viewed in :download:`file form
+</_static/neutron.policy.yaml.sample>`.
+
+.. important::
+
+   The sample policy file is auto-generated from neutron when this
+   documentation is built. You must ensure your version of neutron
+   matches the version of this documentation.
+
+.. literalinclude:: /_static/neutron.policy.yaml.sample
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 00000000000..8d754b7fb22
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,9 @@
+========================
+Neutron Policy Reference
+========================
+
+The following is an overview of all available policies in neutron.
+For a sample configuration file, refer to :doc:`/configuration/policy-sample`.
+
+.. show-policy::
+      :config-file: etc/oslo-policy-generator/policy.conf