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

@@ -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

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

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

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

etc/os-win-config-generator.conf

@@ -0,0 +1,5 @@
+[DEFAULT]
+output_file = etc/os-win.conf.sample
+wrap_width = 80
+
+namespace = os_win

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