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.

Note that this commit just adds the configuration references
for existing genconfig entries. I haven't checked there are options
uncovered. If any, this will be a potential future work.

Part of doc-migration work

Change-Id: I4e150b6045e5e9c56cbe7262b31ee0d82dcb6c69

.gitignore

@@ -6,6 +6,7 @@ cover/
 covhtml/
 dist/
 doc/build
+doc/source/_static/config_samples/*.sample
 etc/*.sample
 *.DS_Store
 *.pyc

doc/source/conf.py

@@ -22,7 +22,9 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'openstackdocstheme'
+    'openstackdocstheme',
+    'oslo_config.sphinxext',
+    'oslo_config.sphinxconfiggen',
 ]
 
 # openstackdocstheme options
@@ -61,7 +63,7 @@ pygments_style = 'sphinx'
 # html_theme_path = ["."]
 # html_theme = '_theme'
 html_theme = 'openstackdocs'
-# html_static_path = ['static']
+html_static_path = ['_static']
 
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
@@ -80,3 +82,22 @@ latex_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+
+# -- Options for oslo_config.sphinxconfiggen ---------------------------------
+
+_config_generator_config_files = [
+    'bgp_dragent.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/bgp_dragent.rst

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

doc/source/configuration/index.rst

@@ -0,0 +1,31 @@
+=====================
+Configuration Options
+=====================
+
+This section provides a list of all possible options for each
+configuration file.
+
+Configuration Reference
+-----------------------
+
+neutron-dynamic-routing uses the following configuration files for its
+various services.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *
+
+Sample Configuration Files
+--------------------------
+
+The following are sample configuration files for neutron-dynamic-routing.
+These are generated from code and reflect the current state of code
+in the neutron-dynamic-routing repository.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   samples/*

doc/source/configuration/samples/bgp_dragent.rst

@@ -0,0 +1,8 @@
+======================
+Sample bgp_dragent.ini
+======================
+
+This sample configuration can also be viewed in `the raw format
+<../../_static/config_samples/bgp_dragent.conf.sample>`_.
+
+.. literalinclude:: ../../_static/config_samples/bgp_dragent.conf.sample

doc/source/index.rst

@@ -36,6 +36,7 @@ Contents
 
     install/index
     admin/index
+    configuration/index
     reference/index
     cli/index
     contributor/index