doc: Add policy reference

This is the preparation of migration to DocumendedRuleDefault.

Partially Implements: blueprint neutron-policy-in-code

Change-Id: I1d10f5db43167a04546565545d7d21010d16a808

.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

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\/.*',

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

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

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
+Configuration
-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
------------------------
 
 .. 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
+   Policy Reference <policy>
-   linuxbridge-agent.rst
+   policy-sample
-   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

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

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