From 89158e00398fafbcbe4a0bb010890a3ac6f0b82a Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Thu, 13 Jul 2017 06:34:22 +0000 Subject: [PATCH] Add auto-generated config reference oslo.config provides sphinx extensions to generate config reference and sample config files. This commit enables the auto-generation of the networking config reference. Part of doc-migration work Suppress pyroute2 warning to pass the doc build. Change-Id: I74f0def7110674a6a735af77b9b07fb679b2959d --- .gitignore | 1 + doc/source/conf.py | 58 +++++++++++++++--- doc/source/configuration/dhcp-agent.rst | 6 ++ doc/source/configuration/index.rst | 61 +++++++++++++++++++ doc/source/configuration/l3-agent.rst | 9 +++ .../configuration/linuxbridge-agent.rst | 6 ++ doc/source/configuration/macvtap-agent.rst | 6 ++ doc/source/configuration/metadata-agent.rst | 6 ++ doc/source/configuration/metering-agent.rst | 6 ++ doc/source/configuration/ml2-conf.rst | 6 ++ doc/source/configuration/neutron.rst | 6 ++ .../configuration/openvswitch-agent.rst | 6 ++ .../configuration/samples/dhcp-agent.rst | 8 +++ doc/source/configuration/samples/l3-agent.rst | 8 +++ .../samples/linuxbridge-agent.rst | 8 +++ .../configuration/samples/macvtap-agent.rst | 8 +++ .../configuration/samples/metadata-agent.rst | 8 +++ .../configuration/samples/metering-agent.rst | 8 +++ doc/source/configuration/samples/ml2-conf.rst | 8 +++ doc/source/configuration/samples/neutron.rst | 8 +++ .../samples/openvswitch-agent.rst | 8 +++ .../configuration/samples/sriov-agent.rst | 8 +++ doc/source/configuration/sriov-agent.rst | 6 ++ doc/source/index.rst | 7 +++ 24 files changed, 263 insertions(+), 7 deletions(-) create mode 100644 doc/source/configuration/dhcp-agent.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/l3-agent.rst create mode 100644 doc/source/configuration/linuxbridge-agent.rst create mode 100644 doc/source/configuration/macvtap-agent.rst create mode 100644 doc/source/configuration/metadata-agent.rst create mode 100644 doc/source/configuration/metering-agent.rst create mode 100644 doc/source/configuration/ml2-conf.rst create mode 100644 doc/source/configuration/neutron.rst create mode 100644 doc/source/configuration/openvswitch-agent.rst create mode 100644 doc/source/configuration/samples/dhcp-agent.rst create mode 100644 doc/source/configuration/samples/l3-agent.rst create mode 100644 doc/source/configuration/samples/linuxbridge-agent.rst create mode 100644 doc/source/configuration/samples/macvtap-agent.rst create mode 100644 doc/source/configuration/samples/metadata-agent.rst create mode 100644 doc/source/configuration/samples/metering-agent.rst create mode 100644 doc/source/configuration/samples/ml2-conf.rst create mode 100644 doc/source/configuration/samples/neutron.rst create mode 100644 doc/source/configuration/samples/openvswitch-agent.rst create mode 100644 doc/source/configuration/samples/sriov-agent.rst create mode 100644 doc/source/configuration/sriov-agent.rst diff --git a/.gitignore b/.gitignore index 57d35630694..cea9c159619 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ cover/ covhtml/ dist/ doc/build +doc/source/_static/config-samples/*.sample etc/*.sample etc/neutron/plugins/ml2/*.sample *.DS_Store diff --git a/doc/source/conf.py b/doc/source/conf.py index e54339d5dc3..f840ac7b836 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,9 +26,20 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import logging import os import sys + +# NOTE(amotoki): In case of oslo_config.sphinxext is enabled, +# when resolving automodule neutron.tests.functional.db.test_migrations, +# sphinx accesses tests/functional/__init__.py is processed, +# eventlet.monkey_patch() is called and monkey_patch() tries to access +# pyroute2.common.__class__ attribute. It raises pyroute2 warning and +# it causes sphinx build failure due to warning-is-error = 1. +# To pass sphinx build, ignore pyroute2 warning explicitly. +logging.getLogger('pyroute2').setLevel(logging.ERROR) + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -41,13 +52,17 @@ sys.path.append(os.path.abspath("ext")) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.coverage', - 'sphinx.ext.ifconfig', - 'sphinx.ext.graphviz', - 'sphinx.ext.todo', - 'openstackdocstheme', - 'support_matrix'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.ifconfig', + 'sphinx.ext.graphviz', + 'sphinx.ext.todo', + 'openstackdocstheme', + 'support_matrix', + 'oslo_config.sphinxext', + 'oslo_config.sphinxconfiggen', +] # openstackdocstheme options repository_name = 'openstack/neutron' @@ -231,3 +246,32 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +# -- Options for oslo_config.sphinxconfiggen --------------------------------- + +_config_generator_config_files = [ + 'dhcp_agent.ini', + 'l3_agent.ini', + 'linuxbridge_agent.ini', + 'macvtap_agent.ini', + 'metadata_agent.ini', + 'metering_agent.ini', + 'ml2_conf.ini', + 'neutron.conf', + 'openvswitch_agent.ini', + 'sriov_agent.ini', +] + + +def _get_config_generator_config_definition(config_file): + config_file_path = '../../etc/oslo-config-generator/%s' % conf + # oslo_config.sphinxconfiggen appends '.conf.sample' to the filename, + # strip file extentension (.conf or .ini). + output_file_path = '_static/config-samples/%s' % conf.rsplit('.', 1)[0] + return (config_file_path, output_file_path) + + +config_generator_config_file = [ + _get_config_generator_config_definition(conf) + for conf in _config_generator_config_files +] diff --git a/doc/source/configuration/dhcp-agent.rst b/doc/source/configuration/dhcp-agent.rst new file mode 100644 index 00000000000..90c0c86e4e7 --- /dev/null +++ b/doc/source/configuration/dhcp-agent.rst @@ -0,0 +1,6 @@ +============== +dhcp_agent.ini +============== + +.. show-options:: + :config-file: etc/oslo-config-generator/dhcp_agent.ini diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000000..ef03e3b4668 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,61 @@ +.. _configuring: + +============================= +Neutron Configuration Options +============================= + +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 +----------------------- + +.. 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 + +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/l3-agent.rst b/doc/source/configuration/l3-agent.rst new file mode 100644 index 00000000000..2c3bb257a2b --- /dev/null +++ b/doc/source/configuration/l3-agent.rst @@ -0,0 +1,9 @@ +============ +l3_agent.ini +============ + +.. show-options:: + + neutron.az.agent + neutron.base.agent + neutron.l3.agent diff --git a/doc/source/configuration/linuxbridge-agent.rst b/doc/source/configuration/linuxbridge-agent.rst new file mode 100644 index 00000000000..a1af313d66c --- /dev/null +++ b/doc/source/configuration/linuxbridge-agent.rst @@ -0,0 +1,6 @@ +===================== +linuxbridge_agent.ini +===================== + +.. show-options:: + :config-file: etc/oslo-config-generator/linuxbridge_agent.ini diff --git a/doc/source/configuration/macvtap-agent.rst b/doc/source/configuration/macvtap-agent.rst new file mode 100644 index 00000000000..382887b5aa2 --- /dev/null +++ b/doc/source/configuration/macvtap-agent.rst @@ -0,0 +1,6 @@ +================= +macvtap_agent.ini +================= + +.. show-options:: + :config-file: etc/oslo-config-generator/macvtap_agent.ini diff --git a/doc/source/configuration/metadata-agent.rst b/doc/source/configuration/metadata-agent.rst new file mode 100644 index 00000000000..78e499f019e --- /dev/null +++ b/doc/source/configuration/metadata-agent.rst @@ -0,0 +1,6 @@ +================== +metadata_agent.ini +================== + +.. show-options:: + :config-file: etc/oslo-config-generator/metadata_agent.ini diff --git a/doc/source/configuration/metering-agent.rst b/doc/source/configuration/metering-agent.rst new file mode 100644 index 00000000000..61ab847d85e --- /dev/null +++ b/doc/source/configuration/metering-agent.rst @@ -0,0 +1,6 @@ +================== +metering_agent.ini +================== + +.. show-options:: + :config-file: etc/oslo-config-generator/metering_agent.ini diff --git a/doc/source/configuration/ml2-conf.rst b/doc/source/configuration/ml2-conf.rst new file mode 100644 index 00000000000..b29abd015d1 --- /dev/null +++ b/doc/source/configuration/ml2-conf.rst @@ -0,0 +1,6 @@ +============ +ml2_conf.ini +============ + +.. show-options:: + :config-file: etc/oslo-config-generator/ml2_conf.ini diff --git a/doc/source/configuration/neutron.rst b/doc/source/configuration/neutron.rst new file mode 100644 index 00000000000..deef3259005 --- /dev/null +++ b/doc/source/configuration/neutron.rst @@ -0,0 +1,6 @@ +============ +neutron.conf +============ + +.. show-options:: + :config-file: etc/oslo-config-generator/neutron.conf diff --git a/doc/source/configuration/openvswitch-agent.rst b/doc/source/configuration/openvswitch-agent.rst new file mode 100644 index 00000000000..2132dbebf7f --- /dev/null +++ b/doc/source/configuration/openvswitch-agent.rst @@ -0,0 +1,6 @@ +===================== +openvswitch_agent.ini +===================== + +.. show-options:: + :config-file: etc/oslo-config-generator/openvswitch_agent.ini diff --git a/doc/source/configuration/samples/dhcp-agent.rst b/doc/source/configuration/samples/dhcp-agent.rst new file mode 100644 index 00000000000..96ef9b2b86a --- /dev/null +++ b/doc/source/configuration/samples/dhcp-agent.rst @@ -0,0 +1,8 @@ +===================== +Sample dhcp_agent.ini +===================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/dhcp_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/dhcp_agent.conf.sample diff --git a/doc/source/configuration/samples/l3-agent.rst b/doc/source/configuration/samples/l3-agent.rst new file mode 100644 index 00000000000..d9978192c26 --- /dev/null +++ b/doc/source/configuration/samples/l3-agent.rst @@ -0,0 +1,8 @@ +=================== +Sample l3_agent.ini +=================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/l3_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/l3_agent.conf.sample diff --git a/doc/source/configuration/samples/linuxbridge-agent.rst b/doc/source/configuration/samples/linuxbridge-agent.rst new file mode 100644 index 00000000000..242754d003b --- /dev/null +++ b/doc/source/configuration/samples/linuxbridge-agent.rst @@ -0,0 +1,8 @@ +============================ +Sample linuxbridge_agent.ini +============================ + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/linuxbridge_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/linuxbridge_agent.conf.sample diff --git a/doc/source/configuration/samples/macvtap-agent.rst b/doc/source/configuration/samples/macvtap-agent.rst new file mode 100644 index 00000000000..cef49a66079 --- /dev/null +++ b/doc/source/configuration/samples/macvtap-agent.rst @@ -0,0 +1,8 @@ +======================== +Sample macvtap_agent.ini +======================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/macvtap_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/macvtap_agent.conf.sample diff --git a/doc/source/configuration/samples/metadata-agent.rst b/doc/source/configuration/samples/metadata-agent.rst new file mode 100644 index 00000000000..79fda11c9c8 --- /dev/null +++ b/doc/source/configuration/samples/metadata-agent.rst @@ -0,0 +1,8 @@ +========================= +Sample metadata_agent.ini +========================= + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/metadata_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/metadata_agent.conf.sample diff --git a/doc/source/configuration/samples/metering-agent.rst b/doc/source/configuration/samples/metering-agent.rst new file mode 100644 index 00000000000..8bb735f9e0b --- /dev/null +++ b/doc/source/configuration/samples/metering-agent.rst @@ -0,0 +1,8 @@ +========================= +Sample metering_agent.ini +========================= + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/metering_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/metering_agent.conf.sample diff --git a/doc/source/configuration/samples/ml2-conf.rst b/doc/source/configuration/samples/ml2-conf.rst new file mode 100644 index 00000000000..b740d6b6af1 --- /dev/null +++ b/doc/source/configuration/samples/ml2-conf.rst @@ -0,0 +1,8 @@ +=================== +Sample ml2_conf.ini +=================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/ml2_conf.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/ml2_conf.conf.sample diff --git a/doc/source/configuration/samples/neutron.rst b/doc/source/configuration/samples/neutron.rst new file mode 100644 index 00000000000..319293cb700 --- /dev/null +++ b/doc/source/configuration/samples/neutron.rst @@ -0,0 +1,8 @@ +=================== +Sample neutron.conf +=================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/neutron.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/neutron.conf.sample diff --git a/doc/source/configuration/samples/openvswitch-agent.rst b/doc/source/configuration/samples/openvswitch-agent.rst new file mode 100644 index 00000000000..2f6d6b7604e --- /dev/null +++ b/doc/source/configuration/samples/openvswitch-agent.rst @@ -0,0 +1,8 @@ +============================ +Sample openvswitch_agent.ini +============================ + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/openvswitch_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/openvswitch_agent.conf.sample diff --git a/doc/source/configuration/samples/sriov-agent.rst b/doc/source/configuration/samples/sriov-agent.rst new file mode 100644 index 00000000000..ae0689a9bd3 --- /dev/null +++ b/doc/source/configuration/samples/sriov-agent.rst @@ -0,0 +1,8 @@ +====================== +Sample sriov_agent.ini +====================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config-samples/sriov_agent.conf.sample>`_. + +.. literalinclude:: ../../_static/config-samples/sriov_agent.conf.sample diff --git a/doc/source/configuration/sriov-agent.rst b/doc/source/configuration/sriov-agent.rst new file mode 100644 index 00000000000..9b712778c5d --- /dev/null +++ b/doc/source/configuration/sriov-agent.rst @@ -0,0 +1,6 @@ +=============== +sriov_agent.ini +=============== + +.. show-options:: + :config-file: etc/oslo-config-generator/sriov_agent.ini diff --git a/doc/source/index.rst b/doc/source/index.rst index 66ef669750c..2f8870e3e81 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,6 +55,13 @@ Networking Guide admin/index +Configuration Reference +----------------------- +.. toctree:: + :maxdepth: 2 + + configuration/index + CLI Reference -------------