From fcd7fcea3ed68113fa5905ac8fab698600dd0114 Mon Sep 17 00:00:00 2001
From: Sean McGinnis <sean_mcginnis@dell.com>
Date: Mon, 9 May 2016 13:12:37 -0500
Subject: [PATCH] Add sample config file to cinder docs
The oslo sphinxconfiggen module was added to the oslo.config
2.3.0 release. This enables config file generation as part of
the sphinx doc generation.
The generated config file will pick up the current config
options from the code base. And as an added bonus, it will
now be published to the docs.openstack.org site for easy
reference or download.
This also puts us inline with what other projects like Nova
are doing for sample config files and is the recommended
method from the Oslo team.
Change-Id: I912a97eb2686d3dc56e50d8641d7bd930179bc18
---
.gitignore | 2 +-
cinder/config/generate_cinder_opts.py | 13 ++--
doc/source/_static/.placeholder | 0
doc/source/conf.py | 6 +-
doc/source/devref/genconfig.rst | 39 ----------
doc/source/index.rst | 8 ++
doc/source/sample_config.rst | 13 ++++
tools/config/check_uptodate.sh | 67 ++++++----------
tools/config/generate_sample.sh | 105 --------------------------
tox.ini | 5 +-
10 files changed, 59 insertions(+), 199 deletions(-)
create mode 100644 doc/source/_static/.placeholder
delete mode 100644 doc/source/devref/genconfig.rst
create mode 100644 doc/source/sample_config.rst
delete mode 100755 tools/config/generate_sample.sh
diff --git a/.gitignore b/.gitignore
index 293c3cab89a..e27f5c11492 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,12 +24,12 @@ instances
keeper
keys
local_settings.py
-tools/conf/cinder.conf*
tools/lintstack.head.py
tools/pylint_exceptions
tags
# Files created by Sphinx build
doc/build
+doc/source/_static/cinder.conf.sample
# Files created by releasenotes build
releasenotes/build
diff --git a/cinder/config/generate_cinder_opts.py b/cinder/config/generate_cinder_opts.py
index 763d6ec1b16..fba3cea01b3 100644
--- a/cinder/config/generate_cinder_opts.py
+++ b/cinder/config/generate_cinder_opts.py
@@ -16,8 +16,12 @@ import os
import subprocess
import textwrap
+BASEDIR = os.path.split(os.path.realpath(__file__))[0] + "/../../"
+
+
if __name__ == "__main__":
- opt_file = open("cinder/opts.py", 'a')
+ os.chdir(BASEDIR)
+ opt_file = open("cinder/opts.py", 'w')
opt_dict = {}
dir_trees_list = []
REGISTER_OPTS_STR = "CONF.register_opts("
@@ -42,13 +46,12 @@ if __name__ == "__main__":
opt_file.write("import itertools\n\n")
- targetdir = os.environ['TARGETDIR']
- basedir = os.environ['BASEDIRESC']
+ targetdir = 'cinder'
common_string = ('find ' + targetdir + ' -type f -name "*.py" ! '
'-path "*/tests/*" -exec grep -l "%s" {} '
- '+ | sed -e "s/^' + basedir +
- '\///g" | sort -u')
+ '+ | sed -e "s|^' + BASEDIR +
+ '|/|g" | sort -u')
cmd_opts = common_string % REGISTER_OPTS_STR
output_opts = subprocess.check_output('{}'.format(cmd_opts), shell = True)
diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a0fec022b05..f70900170d8 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -34,9 +34,13 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.ifconfig',
'sphinx.ext.graphviz',
'oslosphinx',
- 'stevedore.sphinxext'
+ 'stevedore.sphinxext',
+ 'oslo_config.sphinxconfiggen',
]
+config_generator_config_file = '../../cinder/config/cinder-config-generator.conf'
+sample_config_basename = '_static/cinder'
+
# autodoc generation is a bit aggressive and a nuisance
# when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1"
# in your terminal to disable
diff --git a/doc/source/devref/genconfig.rst b/doc/source/devref/genconfig.rst
deleted file mode 100644
index f7a055770b6..00000000000
--- a/doc/source/devref/genconfig.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Generation of Sample Configuration Options
-==========================================
-
-opts.py
--------
-This file is dynamically created through the following commands and is used
-in the generation of the cinder.conf.sample file by the oslo config generator.
-It is kept in tree because deployers cannot run tox -e genconfig due to
-dependency issues. To generate this file only, use the command 'tox -e genopts'.
-To generate the cinder.conf.sample file use the command 'tox -e genconfig'.
-
-tox -e genconfig
-----------------
-This command will generate a new cinder.conf.sample file by running the
-cinder/tools/config/generate_sample.sh script.
-
-tox -e genopts
---------------
-This command dynamically generates the opts.py file only in the
-event that new configuration options have been added. To do this it
-runs the generate_sample.sh with the --nosamplefile option.
-
-check_uptodate.sh
------------------
-This script will check that the opts.py file exists and if it does, it
-will then create a temp opts.py file to verify that the current opts.py
-file is up to date with all new configuration options that may have been
-added. If it is not up to date it will suggest the generation of a new
-file using 'tox -e genopts'.
-
-generate_sample.sh
-------------------
-This script is responsible for calling the generate_cinder_opts.py file
-which dynamically generates the opts.py file by parsing through the entire
-cinder project. All instances of CONF.register_opt() and CONF.register_opts()
-are collected and the needed arguments are pulled out of those methods. A
-list of the options being registered is created to be written to the opts.py file.
-Later, the oslo config generator takes in the opts.py file, parses through
-those lists and creates the sample file.
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9044bedb05f..0fee7585e1d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -52,6 +52,14 @@ API Extensions
Go to http://api.openstack.org for information about Cinder API extensions.
+Sample Configuration File
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ sample_config
+
Outstanding Documentation Tasks
===============================
diff --git a/doc/source/sample_config.rst b/doc/source/sample_config.rst
new file mode 100644
index 00000000000..3c366492ac2
--- /dev/null
+++ b/doc/source/sample_config.rst
@@ -0,0 +1,13 @@
+============================
+Cinder Configuration Options
+============================
+
+The following is a sample Cinder configuration for adaptation and use. It is
+auto-generated from Cinder when this documentation is built, so if you are
+having issues with an option, please compare your version of Cinder with the
+version of this documentation.
+
+The sample configuration can also be viewed in
+`file form <_static/cinder.conf.sample>`_.
+
+.. literalinclude:: _static/cinder.conf.sample
diff --git a/tools/config/check_uptodate.sh b/tools/config/check_uptodate.sh
index 5de8909b192..77dcce064c3 100755
--- a/tools/config/check_uptodate.sh
+++ b/tools/config/check_uptodate.sh
@@ -1,57 +1,34 @@
#!/usr/bin/env bash
-CHECKOPTS=0
-if [ "$1" == "--checkopts" ]; then
- CHECKOPTS=1
-fi
-
-PROJECT_NAME=${PROJECT_NAME:-cinder}
-CFGFILE_NAME=${PROJECT_NAME}.conf.sample
-
-if [ $CHECKOPTS -eq 1 ]; then
- if [ ! -e cinder/opts.py ]; then
+if [ ! -e cinder/opts.py ]; then
+ echo -en "\n\n#################################################"
+ echo -en "\nERROR: cinder/opts.py file is missing."
+ echo -en "\n#################################################\n"
+ exit 1
+else
+ mv cinder/opts.py cinder/opts.py.orig
+ tox -e genopts &> /dev/null
+ if [ $? -ne 0 ]; then
echo -en "\n\n#################################################"
- echo -en "\nERROR: cinder/opts.py file is missing."
- echo -en "\n#################################################\n"
+ echo -en "\nERROR: Non-zero exit from generate_cinder_opts.py."
+ echo -en "\n See output above for details.\n"
+ echo -en "#################################################\n"
+ mv cinder/opts.py.orig cinder/opts.py
exit 1
else
- mv cinder/opts.py cinder/opts.py.orig
- tox -e genopts &> /dev/null
+ diff cinder/opts.py.orig cinder/opts.py
if [ $? -ne 0 ]; then
- echo -en "\n\n#################################################"
- echo -en "\nERROR: Non-zero exit from generate_cinder_opts.py."
- echo -en "\n See output above for details.\n"
- echo -en "#################################################\n"
+ echo -en "\n\n########################################################"
+ echo -en "\nERROR: Configuration options change detected."
+ echo -en "\n A new cinder/opts.py file must be generated."
+ echo -en "\n Run 'tox -e genopts' from the base directory"
+ echo -en "\n and add the result to your commit."
+ echo -en "\n########################################################\n\n"
+ rm cinder/opts.py
mv cinder/opts.py.orig cinder/opts.py
exit 1
else
- diff cinder/opts.py.orig cinder/opts.py
- if [ $? -ne 0 ]; then
- echo -en "\n\n########################################################"
- echo -en "\nERROR: Configuration options change detected."
- echo -en "\n A new cinder/opts.py file must be generated."
- echo -en "\n Run 'tox -e genopts' from the base directory"
- echo -en "\n and add the result to your commit."
- echo -en "\n########################################################\n\n"
- rm cinder/opts.py
- mv cinder/opts.py.orig cinder/opts.py
- exit 1
- else
- rm cinder/opts.py.orig
- fi
+ rm cinder/opts.py.orig
fi
fi
-else
-
- tox -e genconfig &> /dev/null
-
- if [ -e etc/${PROJECT_NAME}/${CFGFILE_NAME} ]; then
- CFGFILE=etc/${PROJECT_NAME}/${CFGFILE_NAME}
- rm -f $CFGFILE
- else
- echo -en "\n\n####################################################"
- echo -en "\n${0##*/}: Can't find config file."
- echo -en "\n####################################################\n\n"
- exit 1
- fi
fi
diff --git a/tools/config/generate_sample.sh b/tools/config/generate_sample.sh
deleted file mode 100755
index e53a7be6ed2..00000000000
--- a/tools/config/generate_sample.sh
+++ /dev/null
@@ -1,105 +0,0 @@
-#!/usr/bin/env bash
-
-# Generate sample configuration for your project.
-#
-# Aside from the command line flags, it also respects a config file which
-# should be named oslo.config.generator.rc and be placed in the same directory.
-#
-# You can then export the following variables:
-# CINDER_CONFIG_GENERATOR_EXTRA_MODULES: list of modules to interrogate for options.
-# CINDER_CONFIG_GENERATOR_EXTRA_LIBRARIES: list of libraries to discover.
-# CINDER_CONFIG_GENERATOR_EXCLUDED_FILES: list of files to remove from automatic listing.
-
-BASEDIR=${BASEDIR:-`pwd`}
-
-NOSAMPLE=0
-if [ ! -z ${2} ] ; then
- if [ "${2}" == "--nosamplefile" ]; then
- NOSAMPLE=1
- fi
-fi
-
-print_error ()
-{
- echo -en "\n\n##########################################################"
- echo -en "\nERROR: ${0} was not called from tox."
- echo -en "\n Execute 'tox -e genconfig' for cinder.conf.sample"
- echo -en "\n generation."
- echo -en "\n##########################################################\n\n"
-}
-
-if [ -z ${1} ] ; then
- print_error
- exit 1
-fi
-
-if [ ${1} != "from_tox" ] ; then
- print_error
- exit 1
-fi
-
-if ! [ -d $BASEDIR ] ; then
- echo "${0##*/}: missing project base directory" >&2 ; exit 1
-elif [[ $BASEDIR != /* ]] ; then
- BASEDIR=$(cd "$BASEDIR" && pwd)
-fi
-
-PACKAGENAME=${PACKAGENAME:-$(python setup.py --name)}
-TARGETDIR=$BASEDIR/$PACKAGENAME
-if ! [ -d $TARGETDIR ] ; then
- echo "${0##*/}: invalid project package name" >&2 ; exit 1
-fi
-
-BASEDIRESC=`echo $BASEDIR | sed -e 's/\//\\\\\//g'`
-find $TARGETDIR -type f -name "*.pyc" -delete
-
-export TARGETDIR=$TARGETDIR
-export BASEDIRESC=$BASEDIRESC
-
-if [ -e $TARGETDIR/opts.py ] ; then
- mv $TARGETDIR/opts.py $TARGETDIR/opts.py.bak
-fi
-
-python cinder/config/generate_cinder_opts.py
-
-if [ $? -ne 0 ] ; then
- echo -en "\n\n#################################################"
- echo -en "\nERROR: Non-zero exit from generate_cinder_opts.py."
- echo -en "\n See output above for details.\n"
- echo -en "#################################################\n"
- if [ -e $TARGETDIR/opts.py.bak ] ; then
- mv $TARGETDIR/opts.py.bak $TARGETDIR/opts.py
- fi
- exit 1
-fi
-
-if [ $NOSAMPLE -eq 0 ] ; then
- oslo-config-generator --config-file=cinder/config/cinder-config-generator.conf
-
- if [ $? -ne 0 ] ; then
- echo -en "\n\n#################################################"
- echo -en "\nERROR: Non-zero exit from oslo-config-generator."
- echo -en "\n See output above for details.\n"
- echo -en "#################################################\n"
- mv $TARGETDIR/opts.py.bak $TARGETDIR/opts.py
- exit 1
- fi
-
- diff $TARGETDIR/opts.py $TARGETDIR/opts.py.bak &> /dev/null
-
- if [ $? -ne 0 ] ; then
- mv $TARGETDIR/opts.py.bak $TARGETDIR/opts.py
- else
- rm -f $TARGETDIR/opts.py.bak
- fi
-
- if [ ! -s ./etc/cinder/cinder.conf.sample ] ; then
- echo -en "\n\n#########################################################"
- echo -en "\nERROR: etc/cinder/cinder.sample.conf not created properly."
- echo -en "\n See above output for details.\n"
- echo -en "###########################################################\n"
- exit 1
- fi
-else
- rm -f $TARGETDIR/opts.py.bak
-fi
diff --git a/tox.ini b/tox.ini
index 326a1a5f633..25673862892 100644
--- a/tox.ini
+++ b/tox.ini
@@ -41,7 +41,6 @@ commands =
flake8 {posargs} .
# Check that .po and .pot files are valid:
bash -c "find cinder -type f -regex '.*\.pot?' -print0|xargs -0 -n 1 msgfmt --check-format -o /dev/null"
- {toxinidir}/tools/config/check_uptodate.sh --checkopts
{toxinidir}/tools/config/check_uptodate.sh
{toxinidir}/tools/check_exec.py {toxinidir}/cinder
@@ -70,12 +69,12 @@ commands =
[testenv:genconfig]
sitepackages = False
envdir = {toxworkdir}/pep8
-commands = {toxinidir}/tools/config/generate_sample.sh from_tox
+commands = oslo-config-generator --config-file=cinder/config/cinder-config-generator.conf
[testenv:genopts]
sitepackages = False
envdir = {toxworkdir}/pep8
-commands = {toxinidir}/tools/config/generate_sample.sh from_tox --nosamplefile
+commands = python cinder/config/generate_cinder_opts.py
[testenv:venv]
# NOTE(jaegerandi): This target does not use constraints because