From e27e1831f9a1c2aad9f1ca6a5d893f87ced6bf4d Mon Sep 17 00:00:00 2001
From: Lucian Petrut <lpetrut@cloudbasesolutions.com>
Date: Fri, 10 Nov 2017 15:12:28 +0200
Subject: [PATCH] Add config sample to os-win docs

This change adds an automatically generated config sample to the
os-win docs.

The config sample is generated each time the docs are built, using
the oslo.config sphinxconfiggen extension.

Related-Bug: #1709648

Change-Id: I01f44bf02c92ecfced6d5266caa40683a0a9248e
---
 .gitignore                       |  2 ++
 doc/source/conf.py               |  6 +++++-
 doc/source/index.rst             | 10 +++++-----
 doc/source/sample_config.rst     | 16 ++++++++++++++++
 etc/os-win-config-generator.conf |  5 +++++
 test-requirements.txt            |  1 +
 6 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 doc/source/sample_config.rst
 create mode 100644 etc/os-win-config-generator.conf

diff --git a/.gitignore b/.gitignore
index e6257802..76bdab04 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,6 +43,8 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/_static/os-win.conf.sample
+etc/os-win.conf.sample
 
 # pbr generates these
 AUTHORS
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 626dcb6a..e91ac76c 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'oslo_config.sphinxconfiggen',
     # 'sphinx.ext.intersphinx',
     'oslosphinx'
 ]
@@ -33,6 +34,9 @@ extensions = [
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+config_generator_config_file = '../../etc/os-win-config-generator.conf'
+sample_config_basename = '_static/os-win'
+
 # The master toctree document.
 master_doc = 'index'
 
@@ -56,7 +60,7 @@ pygments_style = 'sphinx'
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = ["."]
 # html_theme = '_theme'
-# html_static_path = ['static']
+html_static_path = ['_static']
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
diff --git a/doc/source/index.rst b/doc/source/index.rst
index cdb06769..56c93cef 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -16,10 +16,10 @@ Contents:
    usage
    contributing
 
-Indices and tables
-==================
+Sample Configuration File
+-------------------------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 1
 
+   sample_config
diff --git a/doc/source/sample_config.rst b/doc/source/sample_config.rst
new file mode 100644
index 00000000..6312c751
--- /dev/null
+++ b/doc/source/sample_config.rst
@@ -0,0 +1,16 @@
+============================
+Os-win Configuration Options
+============================
+
+The following is a sample os-win configuration for adaptation and use.
+
+The sample configuration can also be viewed in :download:`file from
+</_static/os-win.conf.sample>`.
+
+.. important::
+
+   The sample configuration file is auto-generated from os-win when this
+   documentation is built. You must ensure your version of os-win matches the
+   version of this documentation.
+
+.. literalinclude:: /_static/os-win.conf.sample
diff --git a/etc/os-win-config-generator.conf b/etc/os-win-config-generator.conf
new file mode 100644
index 00000000..3f697bad
--- /dev/null
+++ b/etc/os-win-config-generator.conf
@@ -0,0 +1,5 @@
+[DEFAULT]
+output_file = etc/os-win.conf.sample
+wrap_width = 80
+
+namespace = os_win
diff --git a/test-requirements.txt b/test-requirements.txt
index 728868a5..adc3d735 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -9,6 +9,7 @@ ddt>=1.0.1 # MIT
 python-subunit>=0.0.18 # Apache-2.0/BSD
 docutils>=0.11 # OSI-Approved Open Source, Public Domain
 sphinx>=1.6.2 # BSD
+oslo.config>=4.6.0 # Apache-2.0
 oslosphinx>=4.7.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD