From fcd7fcea3ed68113fa5905ac8fab698600dd0114 Mon Sep 17 00:00:00 2001 From: Sean McGinnis 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