Holiday docs and comment formatting cleanup

Change-Id: Ia4ca88c67d3b94e306a79a669805a2fa1b0dc069

HACKING.rst

@@ -15,6 +15,16 @@ https://github.com/openstack-dev/devstack.git.  Besides the master branch that
 tracks the OpenStack trunk branches a separate branch is maintained for all
 OpenStack releases starting with Diablo (stable/diablo).
 
+Contributing code to DevStack follows the usual OpenStack process as described
+in `How To Contribute`__ in the OpenStack wiki.  `DevStack's LaunchPad project`__
+contains the usual links for blueprints, bugs, tec.
+
+__ contribute_
+.. _contribute: http://wiki.openstack.org/HowToContribute.
+
+__ lp_
+.. _lp: https://launchpad.net/~devstack
+
 The primary script in DevStack is ``stack.sh``, which performs the bulk of the
 work for DevStack's use cases.  There is a subscript ``functions`` that contains
 generally useful shell functions and is used by a number of the scripts in
@@ -53,8 +63,8 @@ configuration of the user environment::
     source $TOP_DIR/openrc
 
 ``stack.sh`` is a rather large monolithic script that flows through from beginning
-to end.  The process of breaking it down into project-level sub-scripts has begun
+to end.  The process of breaking it down into project-level sub-scripts is nearly
-with the introduction of ``lib/cinder`` and ``lib/ceilometer``.
+complete and should make ``stack.sh`` easier to read and manage.
 
 These library sub-scripts have a number of fixed entry points, some of which may
 just be stubs.  These entry points will be called by ``stack.sh`` in the
@@ -71,6 +81,12 @@ There is a sub-script template in ``lib/templates`` to be used in creating new
 service sub-scripts.  The comments in ``<>`` are meta comments describing
 how to use the template and should be removed.
 
+In order to show the dependencies and conditions under which project functions
+are executed the top-level conditional testing for things like ``is_service_enabled``
+should be done in ``stack.sh``.  There may be nested conditionals that need
+to be in the sub-script, such as testing for keystone being enabled in
+``configure_swift()``.
+
 
 Documentation
 -------------

exercises/quantum-adv-test.sh

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 #
 
-# **quantum.sh**
+# **quantum-adv-test.sh**
 
-# We will use this test to perform integration testing of nova and
+# Perform integration testing of Nova and other components with Quantum.
-# other components with Quantum.
 
 echo "*********************************************************************"
 echo "Begin DevStack Exercise: $0"
@@ -14,6 +13,7 @@ echo "*********************************************************************"
 # only the first error that occured.
 
 set -o errtrace
+
 trap failed ERR
 failed() {
     local r=$?
@@ -30,17 +30,8 @@ failed() {
 # an error.  It is also useful for following allowing as the install occurs.
 set -o xtrace
 
-#------------------------------------------------------------------------------
-# Quantum config check
-#------------------------------------------------------------------------------
-# Warn if quantum is not enabled
-if [[ ! "$ENABLED_SERVICES" =~ "q-svc" ]]; then
-    echo "WARNING: Running quantum test without enabling quantum"
-fi
-
-#------------------------------------------------------------------------------
 # Environment
-#------------------------------------------------------------------------------
+# -----------
 
 # Keep track of the current directory
 EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
@@ -62,9 +53,8 @@ source $TOP_DIR/lib/quantum
 # Import exercise configuration
 source $TOP_DIR/exerciserc
 
-#------------------------------------------------------------------------------
+# Quantum Settings
-# Test settings for quantum
+# ----------------
-#------------------------------------------------------------------------------
 
 TENANTS="DEMO1"
 # TODO (nati)_Test public network
@@ -106,24 +96,17 @@ PUBLIC_ROUTER1_NET="admin-net1"
 DEMO1_ROUTER1_NET="demo1-net1"
 DEMO2_ROUTER1_NET="demo2-net1"
 
-#------------------------------------------------------------------------------
-# Keystone settings.
-#------------------------------------------------------------------------------
 KEYSTONE="keystone"
 
-#------------------------------------------------------------------------------
+# Manually create a token by querying keystone (sending JSON data).  Keystone
-# Get a token for clients that don't support service catalog
-#------------------------------------------------------------------------------
-
-# manually create a token by querying keystone (sending JSON data).  Keystone
 # returns a token and catalog of endpoints.  We use python to parse the token
 # and save it.
 
 TOKEN=`keystone token-get | grep ' id ' | awk '{print $4}'`
 
-#------------------------------------------------------------------------------
+# Various functions
-# Various functions.
+# -----------------
-#------------------------------------------------------------------------------
+
 function foreach_tenant {
     COMMAND=$1
     for TENANT in ${TENANTS//,/ };do
@@ -194,8 +177,7 @@ function confirm_server_active {
     if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
         echo "server '$VM_UUID' did not become active!"
         false
-fi
+    fi
-
 }
 
 function add_tenant {
@@ -214,23 +196,15 @@ function add_tenant {
 function remove_tenant {
     local TENANT=$1
     local TENANT_ID=$(get_tenant_id $TENANT)
-
     $KEYSTONE tenant-delete $TENANT_ID
 }
 
 function remove_user {
     local USER=$1
     local USER_ID=$(get_user_id $USER)
-
     $KEYSTONE user-delete $USER_ID
 }
 
-
-
-#------------------------------------------------------------------------------
-# "Create" functions
-#------------------------------------------------------------------------------
-
 function create_tenants {
     source $TOP_DIR/openrc admin admin
     add_tenant demo1 demo1 demo1
@@ -383,9 +357,9 @@ function all {
     delete_all
 }
 
-#------------------------------------------------------------------------------
+# Test functions
-# Test functions.
+# --------------
-#------------------------------------------------------------------------------
+
 function test_functions {
     IMAGE=$(get_image_id)
     echo $IMAGE
@@ -400,9 +374,9 @@ function test_functions {
     echo $NETWORK_ID
 }
 
-#------------------------------------------------------------------------------
+# Usage and main
-# Usage and main.
+# --------------
-#------------------------------------------------------------------------------
+
 usage() {
     echo "$0: [-h]"
     echo "  -h, --help              Display help message"
@@ -473,10 +447,9 @@ main() {
     fi
 }
 
+# Kick off script
+# ---------------
 
-#-------------------------------------------------------------------------------
-# Kick off script.
-#-------------------------------------------------------------------------------
 echo $*
 main $*
 

lib/ceilometer

@@ -1,9 +1,9 @@
 # lib/ceilometer
-# Install and start Ceilometer service
+# Install and start **Ceilometer** service
+
 # To enable, add the following to localrc
 # ENABLED_SERVICES+=ceilometer-acompute,ceilometer-acentral,ceilometer-collector,ceilometer-api
 
-
 # Dependencies:
 # - functions
 # - OS_AUTH_URL for auth in api
@@ -12,12 +12,12 @@
 
 # stack.sh
 # ---------
-# install_XXX
+# install_ceilometer
-# configure_XXX
+# configure_ceilometer
-# init_XXX
+# init_ceilometer
-# start_XXX
+# start_ceilometer
-# stop_XXX
+# stop_ceilometer
-# cleanup_XXX
+# cleanup_ceilometer
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -27,17 +27,18 @@ set +o xtrace
 # Defaults
 # --------
 
-# set up default directories
+# Set up default directories
 CEILOMETER_DIR=$DEST/ceilometer
+CEILOMETER_CONF_DIR=/etc/ceilometer
+CEILOMETER_CONF=$CEILOMETER_CONF_DIR/ceilometer.conf
+CEILOMETER_API_LOG_DIR=/var/log/ceilometer-api
+
 # Support potential entry-points console scripts
 if [ -d $CEILOMETER_DIR/bin ] ; then
     CEILOMETER_BIN_DIR=$CEILOMETER_DIR/bin
 else
     CEILOMETER_BIN_DIR=/usr/local/bin
 fi
-CEILOMETER_CONF_DIR=/etc/ceilometer
-CEILOMETER_CONF=$CEILOMETER_CONF_DIR/ceilometer.conf
-CEILOMETER_API_LOG_DIR=/var/log/ceilometer-api
 
 # cleanup_ceilometer() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up

lib/cinder

@@ -1,5 +1,5 @@
 # lib/cinder
-# Install and start Cinder volume service
+# Install and start **Cinder** volume service
 
 # Dependencies:
 # - functions

lib/databases/mysql

@@ -1,5 +1,5 @@
-# lib/mysql
+# lib/databases/mysql
-# Functions to control the configuration and operation of the MySQL database backend
+# Functions to control the configuration and operation of the **MySQL** database backend
 
 # Dependencies:
 # DATABASE_{HOST,USER,PASSWORD} must be defined

lib/databases/postgresql

@@ -1,5 +1,5 @@
-# lib/postgresql
+# lib/databases/postgresql
-# Functions to control the configuration and operation of the PostgreSQL database backend
+# Functions to control the configuration and operation of the **PostgreSQL** database backend
 
 # Dependencies:
 # DATABASE_{HOST,USER,PASSWORD} must be defined

lib/glance

@@ -1,5 +1,5 @@
 # lib/glance
-# Functions to control the configuration and operation of the Glance service
+# Functions to control the configuration and operation of the **Glance** service
 
 # Dependencies:
 # ``functions`` file
@@ -25,8 +25,6 @@ set +o xtrace
 # Defaults
 # --------
 
-# <define global variables here that belong to this project>
-
 # Set up default directories
 GLANCE_DIR=$DEST/glance
 GLANCECLIENT_DIR=$DEST/python-glanceclient
@@ -141,7 +139,6 @@ function configure_glance() {
     iniset $GLANCE_CACHE_CONF DEFAULT admin_password $SERVICE_PASSWORD
 
     cp -p $GLANCE_DIR/etc/policy.json $GLANCE_POLICY_JSON
-
 }
 
 # init_glance() - Initialize databases, etc.

lib/heat

@@ -1,5 +1,6 @@
 # lib/heat
-# Install and start Heat service
+# Install and start **Heat** service
+
 # To enable, add the following to localrc
 # ENABLED_SERVICES+=,heat,h-api-cfn,h-api-cw,h-eng
 
@@ -8,12 +9,14 @@
 
 # stack.sh
 # ---------
-# install_XXX
+# install_heatclient
-# configure_XXX
+# install_heat
-# init_XXX
+# configure_heatclient
-# start_XXX
+# configure_heat
-# stop_XXX
+# init_heat
-# cleanup_XXX
+# start_heat
+# stop_heat
+# cleanup_heat
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -57,7 +60,7 @@ function configure_heat() {
     HEAT_API_HOST=${HEAT_API_HOST:-$SERVICE_HOST}
     HEAT_API_PORT=${HEAT_API_PORT:-8004}
 
-    # cloudformation api
+    # Cloudformation API
     HEAT_API_CFN_CONF=$HEAT_CONF_DIR/heat-api-cfn.conf
     cp $HEAT_DIR/etc/heat/heat-api-cfn.conf $HEAT_API_CFN_CONF
     iniset $HEAT_API_CFN_CONF DEFAULT debug True
@@ -86,7 +89,7 @@ function configure_heat() {
     iniset $HEAT_API_CFN_PASTE_INI filter:ec2authtoken auth_uri $KEYSTONE_SERVICE_PROTOCOL://$KEYSTONE_SERVICE_HOST:$KEYSTONE_SERVICE_PORT/v2.0
     iniset $HEAT_API_CFN_PASTE_INI filter:ec2authtoken keystone_ec2_uri $KEYSTONE_SERVICE_PROTOCOL://$KEYSTONE_SERVICE_HOST:$KEYSTONE_SERVICE_PORT/v2.0/ec2tokens
 
-    # openstack api
+    # OpenStack API
     HEAT_API_CONF=$HEAT_CONF_DIR/heat-api.conf
     cp $HEAT_DIR/etc/heat/heat-api.conf $HEAT_API_CONF
     iniset $HEAT_API_CONF DEFAULT debug True
@@ -139,7 +142,7 @@ function configure_heat() {
         iniset $HEAT_ENGINE_CONF DEFAULT rpc_backend heat.openstack.common.rpc.impl_qpid
     fi
 
-    # cloudwatch api
+    # Cloudwatch API
     HEAT_API_CW_CONF=$HEAT_CONF_DIR/heat-api-cloudwatch.conf
     cp $HEAT_DIR/etc/heat/heat-api-cloudwatch.conf $HEAT_API_CW_CONF
     iniset $HEAT_API_CW_CONF DEFAULT debug True

lib/keystone

@@ -8,7 +8,6 @@
 # ``SERVICE_TOKEN``
 # ``S3_SERVICE_PORT`` (template backend only)
 
-
 # ``stack.sh`` calls the entry points in this order:
 #
 # install_keystone
@@ -27,8 +26,6 @@ set +o xtrace
 # Defaults
 # --------
 
-# <define global variables here that belong to this project>
-
 # Set up default directories
 KEYSTONE_DIR=$DEST/keystone
 KEYSTONE_CONF_DIR=${KEYSTONE_CONF_DIR:-/etc/keystone}

lib/nova

@@ -1,5 +1,5 @@
 # lib/nova
-# Functions to control the configuration and operation of the XXXX service
+# Functions to control the configuration and operation of the **Nova** service
 
 # Dependencies:
 # ``functions`` file

lib/swift

@@ -1,5 +1,5 @@
 # lib/swift
-# Functions to control the configuration and operation of the swift service
+# Functions to control the configuration and operation of the **Swift** service
 
 # Dependencies:
 # ``functions`` file
@@ -23,10 +23,7 @@ set +o xtrace
 # Defaults
 # --------
 
-# <define global variables here that belong to this project>
-
 # Set up default directories
-
 SWIFT_DIR=$DEST/swift
 SWIFTCLIENT_DIR=$DEST/python-swiftclient
 SWIFT_AUTH_CACHE_DIR=${SWIFT_AUTH_CACHE_DIR:-/var/cache/swift}
@@ -71,6 +68,7 @@ OBJECT_PORT_BASE=6010
 CONTAINER_PORT_BASE=6011
 ACCOUNT_PORT_BASE=6012
 
+
 # Entry Points
 # ------------
 
@@ -293,7 +291,6 @@ EOF
     sudo chown -R $USER:adm ${swift_log_dir}
     sed "s,%SWIFT_LOGDIR%,${swift_log_dir}," $FILES/swift/rsyslog.conf | sudo \
         tee /etc/rsyslog.d/10-swift.conf
-
 }
 
 # configure_swiftclient() - Set config files, create data dirs, etc

lib/tempest

@@ -1,4 +1,5 @@
 # lib/tempest
+# Install and configure Tempest
 
 # Dependencies:
 # ``functions`` file
@@ -23,33 +24,29 @@
 #
 # install_tempest
 # configure_tempest
-# init_tempest
-## start_tempest
-## stop_tempest
-## cleanup_tempest
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
 # Defaults
 # --------
 
-# <define global variables here that belong to this project>
-
 # Set up default directories
-NOVA_SOURCE_DIR=$DEST/nova
 TEMPEST_DIR=$DEST/tempest
 TEMPEST_CONF_DIR=$TEMPEST_DIR/etc
 TEMPEST_CONF=$TEMPEST_CONF_DIR/tempest.conf
 
+NOVA_SOURCE_DIR=$DEST/nova
+
 BUILD_INTERVAL=3
 BUILD_TIMEOUT=400
 
+
 # Entry Points
 # ------------
 
-
 # configure_tempest() - Set config files, create data dirs, etc
 function configure_tempest() {
     local image_lines
@@ -66,7 +63,7 @@ function configure_tempest() {
     local public_network_id
     local tenant_networks_reachable
 
-    #TODO(afazekas):
+    # TODO(afazekas):
     # sudo python setup.py deploy
 
     # This function exits on an error so that errors don't compound and you see
@@ -74,7 +71,7 @@ function configure_tempest() {
     errexit=$(set +o | grep errexit)
     set -o errexit
 
-    #Save IFS
+    # Save IFS
     ifs=$IFS
 
     # Glance should already contain images to be used in tempest
@@ -240,7 +237,6 @@ function configure_tempest() {
     $errexit
 }
 
-
 # install_tempest() - Collect source and prepare
 function install_tempest() {
     git_clone $TEMPEST_REPO $TEMPEST_DIR $TEMPEST_BRANCH