Merge "Add sample config file to cinder docs"

.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 for API reference
 api-ref/build

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']
+    targetdir = 'cinder'
-    basedir = os.environ['BASEDIRESC']
 
     common_string = ('find ' + targetdir + ' -type f -name "*.py" !  '
                      '-path "*/tests/*" -exec grep -l "%s" {} '
-                     '+  | sed -e "s/^' + basedir +
+                     '+  | sed -e "s|^' + BASEDIR +
-                     '\///g" | sort -u')
+                     '|/|g" | sort -u')
 
     cmd_opts = common_string % REGISTER_OPTS_STR
     output_opts = subprocess.check_output('{}'.format(cmd_opts), shell = True)

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

doc/source/devref/genconfig.rst

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

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

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

tools/config/check_uptodate.sh

@@ -1,57 +1,34 @@
 #!/usr/bin/env bash
 
-CHECKOPTS=0
+if [ ! -e cinder/opts.py ]; then
-if [ "$1" == "--checkopts" ]; then
+    echo -en "\n\n#################################################"
-    CHECKOPTS=1
+    echo -en "\nERROR: cinder/opts.py file is missing."
-fi
+    echo -en "\n#################################################\n"
-
+    exit 1
-PROJECT_NAME=${PROJECT_NAME:-cinder}
+else
-CFGFILE_NAME=${PROJECT_NAME}.conf.sample
+    mv cinder/opts.py cinder/opts.py.orig
-
+    tox -e genopts &> /dev/null
-if [ $CHECKOPTS -eq 1 ]; then
+    if [ $? -ne 0 ]; then
-    if [ ! -e cinder/opts.py ]; then
         echo -en "\n\n#################################################"
-        echo -en "\nERROR: cinder/opts.py file is missing."
+        echo -en "\nERROR: Non-zero exit from generate_cinder_opts.py."
-        echo -en "\n#################################################\n"
+        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
+        diff cinder/opts.py.orig cinder/opts.py
-        tox -e genopts &> /dev/null
         if [ $? -ne 0 ]; then
-            echo -en "\n\n#################################################"
+            echo -en "\n\n########################################################"
-            echo -en "\nERROR: Non-zero exit from generate_cinder_opts.py."
+            echo -en "\nERROR: Configuration options change detected."
-            echo -en "\n       See output above for details.\n"
+            echo -en "\n       A new cinder/opts.py file must be generated."
-            echo -en "#################################################\n"
+            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
+            rm cinder/opts.py.orig
-            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
         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

tools/config/generate_sample.sh

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

tox.ini

@@ -52,7 +52,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
 
@@ -81,12 +80,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