openstack/cinder
Code Issues Proposed changes

Add sample config file to cinder docs

Browse Source 
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
This commit is contained in:
Sean McGinnis 2016-05-09 13:12:37 -05:00
parent 8c6e8ee3b9
commit fcd7fcea3e
10 changed files with 59 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

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

13
cinder/config/generate_cinder_opts.py
View File

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

0
doc/source/_static/.placeholder Normal file
View File

6
doc/source/conf.py
View File

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

39
doc/source/devref/genconfig.rst
View File

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

8
doc/source/index.rst
View File

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

13
doc/source/sample_config.rst Normal file
View File

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

67
tools/config/check_uptodate.sh
View File

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

105
tools/config/generate_sample.sh
View File

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

5
tox.ini
View File

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