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

@@ -6,6 +6,7 @@ cover/
 covhtml/
 dist/
 doc/build
+doc/source/_static/config-samples/*.sample
 etc/*.sample
 etc/neutron/plugins/ml2/*.sample
 *.DS_Store

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
+]

doc/source/configuration/dhcp-agent.rst

@@ -0,0 +1,6 @@
+==============
+dhcp_agent.ini
+==============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/dhcp_agent.ini

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

doc/source/configuration/l3-agent.rst

@@ -0,0 +1,9 @@
+============
+l3_agent.ini
+============
+
+.. show-options::
+
+   neutron.az.agent
+   neutron.base.agent
+   neutron.l3.agent

doc/source/configuration/linuxbridge-agent.rst

@@ -0,0 +1,6 @@
+=====================
+linuxbridge_agent.ini
+=====================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/linuxbridge_agent.ini

doc/source/configuration/macvtap-agent.rst

@@ -0,0 +1,6 @@
+=================
+macvtap_agent.ini
+=================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/macvtap_agent.ini

doc/source/configuration/metadata-agent.rst

@@ -0,0 +1,6 @@
+==================
+metadata_agent.ini
+==================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/metadata_agent.ini

doc/source/configuration/metering-agent.rst

@@ -0,0 +1,6 @@
+==================
+metering_agent.ini
+==================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/metering_agent.ini

doc/source/configuration/ml2-conf.rst

@@ -0,0 +1,6 @@
+============
+ml2_conf.ini
+============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/ml2_conf.ini

doc/source/configuration/neutron.rst

@@ -0,0 +1,6 @@
+============
+neutron.conf
+============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/neutron.conf

doc/source/configuration/openvswitch-agent.rst

@@ -0,0 +1,6 @@
+=====================
+openvswitch_agent.ini
+=====================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/openvswitch_agent.ini

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

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

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

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

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

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

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

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

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

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

doc/source/configuration/sriov-agent.rst

@@ -0,0 +1,6 @@
+===============
+sriov_agent.ini
+===============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/sriov_agent.ini

doc/source/index.rst

@@ -55,6 +55,13 @@ Networking Guide
 
    admin/index
 
+Configuration Reference
+-----------------------
+.. toctree::
+   :maxdepth: 2
+
+   configuration/index
+
 CLI Reference
 -------------