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
This commit is contained in:
Sean McGinnis
parent
8c6e8ee3b9
commit
fcd7fcea3e
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
===============================
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
5
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue