Add sphinx extension to build sample config

This commit adds a sphinx extension which can be loaded in a sphinx
config.py to generate a sample config file using oslo-config-generator
during each sphinx build. This can then be incorporated into
documentation as necessary.

Co-Authored-By: Doug Hellmann <doug@doughellmann.com>
Change-Id: I2561155749fc8c6a8e31df1614ca6cdb50b4c001

.gitignore

@@ -15,3 +15,4 @@ dist/
 .testrepository/
 .project
 .pydevproject
+/doc/source/sample.config

doc/source/conf.py

@@ -8,7 +8,10 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # 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', 'oslosphinx']
+extensions = ['sphinx.ext.autodoc', 'oslosphinx',
+              'oslo_config.sphinxconfiggen']
+
+config_generator_config_file = 'config-generator.conf'
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.

doc/source/config-generator.conf

@@ -0,0 +1,3 @@
+[DEFAULT]
+wrap_width = 79
+namespace = oslo.config

doc/source/index.rst

@@ -24,6 +24,7 @@ Contents
    generator
    faq
    contributing
+   sphinxconfiggen
 
 Indices and tables
 ==================

doc/source/sphinxconfiggen.rst

@@ -0,0 +1,24 @@
+====================================
+Sphinx Oslo Sample Config Generation
+====================================
+
+Included with oslo.config is a sphinx extension to generate a sample config
+file at the beginning of each sphinx build. To activate the extension add
+``oslo_config.sphinxgenconfig`` to the list of extensions in your sphinx
+``conf.py``.
+
+Then you just need to use the ``config_generator_config_file`` option to point
+the config generator at the config file which tells it how to generate the
+sample config. If one isn't specified or it doesn't point to a real file the
+sample config file generation will be skipped.
+
+Output File Name
+----------------
+
+By default the sphinx plugin will generate the sample config file and name the
+file sample.config. However, if for whatever reason you'd like the name to be
+more specific to the project name you can use the ``config_sample_basename``
+config option to specify the project name. If it's set the output filename
+will be that value with a .conf.sample extension. For example if you set that
+to be nova the output filename will be nova.conf.sample. You can also put a
+subdirectory off of the srcdir as part of this value.

oslo_config/sphinxconfiggen.py

@@ -0,0 +1,66 @@
+# Copyright 2015 Hewlett-Packard Development Company, L.P.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import os
+
+from oslo_config import generator
+
+
+def generate_sample(app):
+
+    def info(msg):
+        app.info('[%s] %s' % (__name__, msg))
+
+    if not app.config.config_generator_config_file:
+        app.warn("No config_generator_config_file is specified, "
+                 "skipping sample config generation")
+        return
+
+    # If we are given a file that isn't an absolute path, look for it
+    # in the source directory if it doesn't exist.
+    candidates = [
+        app.config.config_generator_config_file,
+        os.path.join(
+            app.srcdir,
+            app.config.config_generator_config_file,
+        ),
+    ]
+    for c in candidates:
+        if os.path.isfile(c):
+            info('reading config generator instructions from %s' % c)
+            config_path = c
+            break
+    else:
+        raise ValueError(
+            "Could not find config_generator_config_file %r" %
+            app.config.config_generator_config_file)
+
+    if app.config.sample_config_basename:
+        out_file = os.path.join(
+            app.srcdir, app.config.sample_config_basename) + '.conf.sample'
+        if not os.path.isdir(os.path.dirname(os.path.abspath(out_file))):
+            os.mkdir(os.path.dirname(os.path.abspath(out_file)))
+    else:
+        file_name = 'sample.config'
+        out_file = os.path.join(app.srcdir, file_name)
+
+    info('writing sample configuration to %s' % out_file)
+    generator.main(args=['--config-file', config_path,
+                         '--output-file', out_file])
+
+
+def setup(app):
+    app.add_config_value('config_generator_config_file', None, 'env')
+    app.add_config_value('sample_config_basename', None, 'env')
+    app.connect('builder-inited', generate_sample)