From 55c5139d79ef09869eea1201c736eee8de3ec651 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki 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-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 +`. + +.. 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