From c314db081ebefe347f76de775dfd9021cf6f024e Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Sat, 22 Jul 2017 18:02:42 +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.

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                                    |  1 +
 doc/source/_static/.placeholder               |  0
 doc/source/conf.py                            | 25 +++++++++++++--
 doc/source/configuration/bgp_dragent.rst      |  6 ++++
 doc/source/configuration/index.rst            | 31 +++++++++++++++++++
 .../configuration/samples/bgp_dragent.rst     |  8 +++++
 doc/source/index.rst                          |  1 +
 7 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/_static/.placeholder
 create mode 100644 doc/source/configuration/bgp_dragent.rst
 create mode 100644 doc/source/configuration/index.rst
 create mode 100644 doc/source/configuration/samples/bgp_dragent.rst

diff --git a/.gitignore b/.gitignore
index 2eb709a7..475071ad 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@ cover/
 covhtml/
 dist/
 doc/build
+doc/source/_static/config_samples/*.sample
 etc/*.sample
 *.DS_Store
 *.pyc
diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder
new file mode 100644
index 00000000..e69de29b
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 24392c94..c825df50 100644
--- a/doc/source/conf.py
+++ b/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
+]
diff --git a/doc/source/configuration/bgp_dragent.rst b/doc/source/configuration/bgp_dragent.rst
new file mode 100644
index 00000000..9bcb5119
--- /dev/null
+++ b/doc/source/configuration/bgp_dragent.rst
@@ -0,0 +1,6 @@
+===============
+bgp_dragent.ini
+===============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/bgp_dragent.ini
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
new file mode 100644
index 00000000..b5616f4f
--- /dev/null
+++ b/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/*
diff --git a/doc/source/configuration/samples/bgp_dragent.rst b/doc/source/configuration/samples/bgp_dragent.rst
new file mode 100644
index 00000000..2c5a26de
--- /dev/null
+++ b/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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4f1e6add..bc93a2ea 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -36,6 +36,7 @@ Contents
 
     install/index
     admin/index
+    configuration/index
     reference/index
     cli/index
     contributor/index