From 006415f41bb67d25a2c132ca939aa5126f550a32 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 10 Aug 2015 15:05:28 -0400 Subject: [PATCH] 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 Change-Id: I2561155749fc8c6a8e31df1614ca6cdb50b4c001 --- .gitignore | 1 + doc/source/conf.py | 5 ++- doc/source/config-generator.conf | 3 ++ doc/source/index.rst | 1 + doc/source/sphinxconfiggen.rst | 24 ++++++++++++ oslo_config/sphinxconfiggen.py | 66 ++++++++++++++++++++++++++++++++ 6 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 doc/source/config-generator.conf create mode 100644 doc/source/sphinxconfiggen.rst create mode 100644 oslo_config/sphinxconfiggen.py diff --git a/.gitignore b/.gitignore index 8edfd0f5..bc7f2824 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ dist/ .testrepository/ .project .pydevproject +/doc/source/sample.config diff --git a/doc/source/conf.py b/doc/source/conf.py index 120ad025..e7969193 100644 --- a/doc/source/conf.py +++ b/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. diff --git a/doc/source/config-generator.conf b/doc/source/config-generator.conf new file mode 100644 index 00000000..0c67e407 --- /dev/null +++ b/doc/source/config-generator.conf @@ -0,0 +1,3 @@ +[DEFAULT] +wrap_width = 79 +namespace = oslo.config diff --git a/doc/source/index.rst b/doc/source/index.rst index 38d7b334..558db84c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,6 +24,7 @@ Contents generator faq contributing + sphinxconfiggen Indices and tables ================== diff --git a/doc/source/sphinxconfiggen.rst b/doc/source/sphinxconfiggen.rst new file mode 100644 index 00000000..9a6bc60c --- /dev/null +++ b/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. diff --git a/oslo_config/sphinxconfiggen.py b/oslo_config/sphinxconfiggen.py new file mode 100644 index 00000000..9235bfd3 --- /dev/null +++ b/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)