@@ -2,7 +2,7 @@

 # **exercise.sh**

-# Keep track of the current devstack directory.

+# Keep track of the current DevStack directory.

 TOP_DIR=$(cd $(dirname "$0") && pwd)

 # Import common functions

@@ -14,11 +14,11 @@ source $TOP_DIR/stackrc

 # Run everything in the exercises/ directory that isn't explicitly disabled

 # comma separated list of script basenames to skip

-# to refrain from exercising euca.sh use SKIP_EXERCISES=euca

+# to refrain from exercising euca.sh use ``SKIP_EXERCISES=euca``

 SKIP_EXERCISES=${SKIP_EXERCISES:-""}

 # comma separated list of script basenames to run

-# to run only euca.sh use RUN_EXERCISES=euca

+# to run only euca.sh use ``RUN_EXERCISES=euca``

 basenames=${RUN_EXERCISES:-""}

 EXERCISE_DIR=$TOP_DIR/exercises

@@ -27,7 +27,7 @@ if [[ -z "${basenames}" ]]; then

     # Locate the scripts we should run

     basenames=$(for b in `ls $EXERCISE_DIR/*.sh`; do basename $b .sh; done)

 else

-    # If RUN_EXERCISES was specified, ignore SKIP_EXERCISES.

+    # If ``RUN_EXERCISES`` was specified, ignore ``SKIP_EXERCISES``.

     SKIP_EXERCISES=

 fi

@@ -56,7 +56,7 @@ for script in $basenames; do

     fi

 done

-# output status of exercise run

+# Output status of exercise run

 echo "====================================================================="

 for script in $skips; do

     echo SKIP $script

@@ -439,7 +439,7 @@ function check_path_perm_sanity {

             echo "*** DEST path element"

             echo "***    ${rebuilt_path}"

             echo "*** appears to have 0700 permissions."

-            echo "*** This is very likely to cause fatal issues for devstack daemons."

+            echo "*** This is very likely to cause fatal issues for DevStack daemons."

             if [[ -n "$SKIP_PATH_SANITY" ]]; then

                 return

@@ -526,8 +526,8 @@ function setup_colorized_logging {

 }

 # These functions are provided for basic fall-back functionality for

-# projects that include parts of devstack (grenade).  stack.sh will

-# override these with more specific versions for devstack (with fancy

+# projects that include parts of DevStack (Grenade).  stack.sh will

+# override these with more specific versions for DevStack (with fancy

 # spinners, etc).  We never override an existing version

 if ! function_exists echo_summary; then

     function echo_summary {

@@ -971,7 +971,7 @@ function get_packages {

 #

 # Only packages required for enabled and collected plugins will included.

 #

-# The same metadata used in the main devstack prerequisite files may be used

+# The same metadata used in the main DevStack prerequisite files may be used

 # in these prerequisite files, see get_packages() for more info.

 function get_plugin_packages {

     local xtrace=$(set +o | grep xtrace)

@@ -1471,7 +1471,7 @@ function fetch_plugins {

         return

     fi

-    echo "Fetching devstack plugins"

+    echo "Fetching DevStack plugins"

     for plugin in ${plugins//,/ }; do

         git_clone_by_name $plugin

     done

@@ -4,7 +4,7 @@

 #

 # Note: this is expected to start running as jenkins

-# Step 1: give back sudoers permissions to devstack

+# Step 1: give back sudoers permissions to DevStack

 TEMPFILE=`mktemp`

 echo "stack ALL=(root) NOPASSWD:ALL" >$TEMPFILE

 chmod 0440 $TEMPFILE

@@ -4,7 +4,7 @@

 # Install and start **Ceilometer** service

 # To enable a minimal set of Ceilometer services, add the following to the

-# localrc section of local.conf:

+# ``localrc`` section of ``local.conf``:

 #

 #   enable_service ceilometer-acompute ceilometer-acentral ceilometer-anotification ceilometer-collector ceilometer-api

 #

@@ -17,14 +17,11 @@

 # of Ceilometer (see within for additional settings):

 #

 #   CEILOMETER_USE_MOD_WSGI:       When True, run the api under mod_wsgi.

-#   CEILOMETER_PIPELINE_INTERVAL:  The number of seconds between pipeline processing

-#                                  runs. Default 600.

-#   CEILOMETER_BACKEND:            The database backend (e.g. 'mysql', 'mongodb', 'es')

-#   CEILOMETER_COORDINATION_URL:   The URL for a group membership service provided

-#                                  by tooz.

+#   CEILOMETER_PIPELINE_INTERVAL:  Seconds between pipeline processing runs. Default 600.

+#   CEILOMETER_BACKEND:            Database backend (e.g. 'mysql', 'mongodb', 'es')

+#   CEILOMETER_COORDINATION_URL:   URL for group membership service provided by tooz.

 #   CEILOMETER_EVENTS:             Enable event collection

-

 # Dependencies:

 #

 # - functions

@@ -94,7 +91,7 @@ function is_ceilometer_enabled {

     return 1

 }

-# create_ceilometer_accounts() - Set up common required ceilometer accounts

+# create_ceilometer_accounts() - Set up common required Ceilometer accounts

 #

 # Project              User         Roles

 # ------------------------------------------------------------------

@@ -117,14 +114,14 @@ function create_ceilometer_accounts {

                 "$CEILOMETER_SERVICE_PROTOCOL://$CEILOMETER_SERVICE_HOST:$CEILOMETER_SERVICE_PORT/"

         fi

         if is_service_enabled swift; then

-            # Ceilometer needs ResellerAdmin role to access swift account stats.

+            # Ceilometer needs ResellerAdmin role to access Swift account stats.

             get_or_add_user_project_role "ResellerAdmin" "ceilometer" $SERVICE_TENANT_NAME

         fi

     fi

 }

-# _cleanup_keystone_apache_wsgi() - Remove wsgi files, disable and remove apache vhost file

+# _cleanup_keystone_apache_wsgi() - Remove WSGI files, disable and remove Apache vhost file

 function _cleanup_ceilometer_apache_wsgi {

     sudo rm -f $CEILOMETER_WSGI_DIR/*

     sudo rm -f $(apache_site_config_for ceilometer)

@@ -149,7 +146,7 @@ function _config_ceilometer_apache_wsgi {

     local ceilometer_apache_conf=$(apache_site_config_for ceilometer)

     local apache_version=$(get_apache_version)

-    # copy proxy vhost and wsgi file

+    # Copy proxy vhost and wsgi file

     sudo cp $CEILOMETER_DIR/ceilometer/api/app.wsgi $CEILOMETER_WSGI_DIR/app

     sudo cp $FILES/apache-ceilometer.template $ceilometer_apache_conf

@@ -189,9 +186,9 @@ function configure_ceilometer {

         sed -i "s/interval:.*/interval: ${CEILOMETER_PIPELINE_INTERVAL}/" $CEILOMETER_CONF_DIR/pipeline.yaml

     fi

-    # the compute and central agents need these credentials in order to

-    # call out to other services' public APIs

-    # the alarm evaluator needs these options to call ceilometer APIs

+    # The compute and central agents need these credentials in order to

+    # call out to other services' public APIs.

+    # The alarm evaluator needs these options to call ceilometer APIs

     iniset $CEILOMETER_CONF service_credentials os_username ceilometer

     iniset $CEILOMETER_CONF service_credentials os_password $SERVICE_PASSWORD

     iniset $CEILOMETER_CONF service_credentials os_tenant_name $SERVICE_TENANT_NAME

@@ -237,7 +234,7 @@ function configure_ceilometer {

 }

 function configure_mongodb {

-    # server package is the same on all

+    # Server package is the same on all

     local packages=mongodb-server

     if is_fedora; then

@@ -250,13 +247,13 @@ function configure_mongodb {

     install_package ${packages}

     if is_fedora; then

-        # ensure smallfiles selected to minimize freespace requirements

+        # Ensure smallfiles is selected to minimize freespace requirements

         sudo sed -i '/--smallfiles/!s/OPTIONS=\"/OPTIONS=\"--smallfiles /' /etc/sysconfig/mongod

         restart_service mongod

     fi

-    # give mongodb time to start-up

+    # Give mongodb time to start-up

     sleep 5

 }

@@ -347,7 +344,7 @@ function start_ceilometer {

         run_process ceilometer-acompute "ceilometer-agent-compute --config-file $CEILOMETER_CONF"

     fi

-    # only die on API if it was actually intended to be turned on

+    # Only die on API if it was actually intended to be turned on

     if is_service_enabled ceilometer-api; then

         echo "Waiting for ceilometer-api to start..."

         if ! wait_for_service $SERVICE_TIMEOUT $CEILOMETER_SERVICE_PROTOCOL://$CEILOMETER_SERVICE_HOST:$CEILOMETER_SERVICE_PORT/v2/; then

@@ -41,7 +41,7 @@ function start_dstat {

 # stop_dstat() stop dstat process

 function stop_dstat {

     # dstat runs as a console, not as a service, and isn't trackable

-    # via the normal mechanisms for devstack. So lets just do a

+    # via the normal mechanisms for DevStack. So lets just do a

     # killall and move on.

     killall dstat || /bin/true

 }

@@ -129,7 +129,7 @@ function init_horizon {

     fi

     enable_apache_site horizon

-    # Remove old log files that could mess with how devstack detects whether Horizon

+    # Remove old log files that could mess with how DevStack detects whether Horizon

     # has been successfully started (see start_horizon() and functions::screen_it())

     # and run_process

     sudo rm -f /var/log/$APACHE_NAME/horizon_*

@@ -53,7 +53,7 @@ IRONIC_HW_EPHEMERAL_DISK=${IRONIC_HW_EPHEMERAL_DISK:-0}

 # The file is composed of multiple lines, each line includes four field

 # separated by white space: IPMI address, MAC address, IPMI username

 # and IPMI password.

-# An example:

+#

 #   192.168.110.107 00:1e:67:57:50:4c root otc123

 IRONIC_IPMIINFO_FILE=${IRONIC_IPMIINFO_FILE:-$IRONIC_DATA_DIR/hardware_info}

@@ -99,10 +99,10 @@ IRONIC_AGENT_KERNEL_URL=${IRONIC_AGENT_KERNEL_URL:-http://tarballs.openstack.org

 IRONIC_AGENT_RAMDISK_URL=${IRONIC_AGENT_RAMDISK_URL:-http://tarballs.openstack.org/ironic-python-agent/coreos/files/coreos_production_pxe_image-oem.cpio.gz}

 # Which deploy driver to use - valid choices right now

-# are 'pxe_ssh', 'pxe_ipmitool', 'agent_ssh' and 'agent_ipmitool'.

+# are ``pxe_ssh``, ``pxe_ipmitool``, ``agent_ssh`` and ``agent_ipmitool``.

 IRONIC_DEPLOY_DRIVER=${IRONIC_DEPLOY_DRIVER:-pxe_ssh}

-#TODO(agordeev): replace 'ubuntu' with host distro name getting

+# TODO(agordeev): replace 'ubuntu' with host distro name getting

 IRONIC_DEPLOY_FLAVOR=${IRONIC_DEPLOY_FLAVOR:-ubuntu $IRONIC_DEPLOY_ELEMENT}

 # Support entry points installation of console scripts

@@ -1,3 +1,5 @@

+#!/bin/bash

+#

 # lib/lvm

 # Configure the default LVM volume group used by Cinder and Nova

@@ -32,8 +34,8 @@ DEFAULT_VOLUME_GROUP_NAME=$VOLUME_GROUP_NAME-default

 BACKING_FILE_SUFFIX=-backing-file

-# Entry Points

-# ------------

+# Functions

+# ---------

 # _clean_lvm_volume_group removes all default LVM volumes

 #

@@ -52,7 +54,7 @@ function _clean_lvm_volume_group {

 function _clean_lvm_backing_file {

     local backing_file=$1

-    # if the backing physical device is a loop device, it was probably setup by devstack

+    # If the backing physical device is a loop device, it was probably setup by DevStack

     if [[ -n "$backing_file" ]] && [[ -e "$backing_file" ]]; then

         local vg_dev=$(sudo losetup -j $backing_file | awk -F':' '/'$BACKING_FILE_SUFFIX'/ { print $1}')

         sudo losetup -d $vg_dev

@@ -55,8 +55,9 @@ NOVA_CELLS_DB=${NOVA_CELLS_DB:-nova_cell}

 NOVA_API_PASTE_INI=${NOVA_API_PASTE_INI:-$NOVA_CONF_DIR/api-paste.ini}

 # NOVA_API_VERSION valid options

-#   - default - setup API end points as nova does out of the box

-#   - v21default - make v21 the default on /v2

+# - default - setup API end points as nova does out of the box

+# - v21default - make v21 the default on /v2

+#

 # NOTE(sdague): this is for transitional testing of the Nova v21 API.

 # Expect to remove in L or M.

 NOVA_API_VERSION=${NOVA_API_VERSION-default}

@@ -77,7 +78,7 @@ EC2_SERVICE_PORT=${EC2_SERVICE_PORT:-8773}

 EC2_SERVICE_PORT_INT=${EC2_SERVICE_PORT_INT:-18773}

 # Option to enable/disable config drive

-# NOTE: Set FORCE_CONFIG_DRIVE="False" to turn OFF config drive

+# NOTE: Set ``FORCE_CONFIG_DRIVE="False"`` to turn OFF config drive

 FORCE_CONFIG_DRIVE=${FORCE_CONFIG_DRIVE:-"True"}

 # Nova supports pluggable schedulers.  The default ``FilterScheduler``

@@ -89,11 +90,11 @@ QEMU_CONF=/etc/libvirt/qemu.conf

 # Set default defaults here as some hypervisor drivers override these

 PUBLIC_INTERFACE_DEFAULT=br100

 FLAT_NETWORK_BRIDGE_DEFAULT=br100

-# set the GUEST_INTERFACE_DEFAULT to some interface on the box so that

-# the default isn't completely crazy. This will match eth*, em*, or

-# the new p* interfaces, then basically picks the first

+# Set ``GUEST_INTERFACE_DEFAULT`` to some interface on the box so that

+# the default isn't completely crazy. This will match ``eth*``, ``em*``, or

+# the new ``p*`` interfaces, then basically picks the first

 # alphabetically. It's probably wrong, however it's less wrong than

-# always using 'eth0' which doesn't exist on new Linux distros at all.

+# always using ``eth0`` which doesn't exist on new Linux distros at all.

 GUEST_INTERFACE_DEFAULT=$(ip link \

     | grep 'state UP' \

     | awk '{print $2}' \

@@ -101,8 +102,8 @@ GUEST_INTERFACE_DEFAULT=$(ip link \

     | grep ^[ep] \

     | head -1)

-# $NOVA_VNC_ENABLED can be used to forcibly enable vnc configuration.

-# In multi-node setups allows compute hosts to not run n-novnc.

+# ``NOVA_VNC_ENABLED`` can be used to forcibly enable VNC configuration.

+# In multi-node setups allows compute hosts to not run ``n-novnc``.

 NOVA_VNC_ENABLED=$(trueorfalse False NOVA_VNC_ENABLED)

 # Get hypervisor configuration

@@ -144,7 +145,7 @@ FLAT_INTERFACE=${FLAT_INTERFACE:-$GUEST_INTERFACE_DEFAULT}

 # running the VM - removing a SPOF and bandwidth bottleneck.

 MULTI_HOST=$(trueorfalse False MULTI_HOST)

-# ``NOVA_ALLOW_MOVE_TO_SAME_HOST` can be set to False in multi node devstack,

+# ``NOVA_ALLOW_MOVE_TO_SAME_HOST`` can be set to False in multi node DevStack,

 # where there are at least two nova-computes.

 NOVA_ALLOW_MOVE_TO_SAME_HOST=$(trueorfalse True NOVA_ALLOW_MOVE_TO_SAME_HOST)

@@ -2,7 +2,7 @@

 #

 # lib/oslo

 #

-# Functions to install oslo libraries from git

+# Functions to install **Oslo** libraries from git

 #

 # We need this to handle the fact that projects would like to use

 # pre-released versions of oslo libraries.

@@ -46,8 +46,9 @@ GITDIR["tooz"]=$DEST/tooz

 # Support entry points installation of console scripts

 OSLO_BIN_DIR=$(get_python_exec_prefix)

-# Entry Points

-# ------------

+

+# Functions

+# ---------

 function _do_install_oslo_lib {

     local name=$1

@@ -1,8 +1,7 @@

 #!/bin/bash

 #

 # lib/rpc_backend

-# Interface for interactig with different rpc backend

-# rpc backend settings

+# Interface for interactig with different RPC backends

 # Dependencies:

 #

@@ -27,10 +26,10 @@ RPC_MESSAGING_PROTOCOL=${RPC_MESSAGING_PROTOCOL:-0.9}

 # messaging server as a service, which it really isn't for multi host

 QPID_HOST=${QPID_HOST:-}

+

 # Functions

 # ---------

-

 # Make sure we only have one rpc backend enabled.

 # Also check the specified rpc backend is available on your platform.

 function check_rpc_backend {

@@ -2,15 +2,18 @@

 #

 # lib/stack

 #

-# These functions are code snippets pulled out of stack.sh for easier

+# These functions are code snippets pulled out of ``stack.sh`` for easier

 # re-use by Grenade.  They can assume the same environment is available

-# as in the lower part of stack.sh, namely a valid stackrc has been sourced

-# as well as all of the lib/* files for the services have been sourced.

+# as in the lower part of ``stack.sh``, namely a valid stackrc has been sourced

+# as well as all of the ``lib/*`` files for the services have been sourced.

 #

 # For clarity, all functions declared here that came from ``stack.sh``

 # shall be named with the prefix ``stack_``.

+# Functions

+# ---------

+

 # Generic service install handles venv creation if confgured for service

 # stack_install_service service

 function stack_install_service {

@@ -38,7 +38,6 @@ fi

 # Set up default directories

 GITDIR["python-swiftclient"]=$DEST/python-swiftclient

-

 SWIFT_DIR=$DEST/swift

 SWIFT_AUTH_CACHE_DIR=${SWIFT_AUTH_CACHE_DIR:-/var/cache/swift}

 SWIFT_APACHE_WSGI_DIR=${SWIFT_APACHE_WSGI_DIR:-/var/www/swift}

@@ -59,7 +58,7 @@ SWIFT_DISK_IMAGE=${SWIFT_DATA_DIR}/drives/images/swift.img

 SWIFT_CONF_DIR=${SWIFT_CONF_DIR:-/etc/swift}

 if is_service_enabled s-proxy && is_service_enabled swift3; then

-    # If we are using swift3, we can default the s3 port to swift instead

+    # If we are using ``swift3``, we can default the S3 port to swift instead

     # of nova-objectstore

     S3_SERVICE_PORT=${S3_SERVICE_PORT:-8080}

 fi

@@ -137,11 +136,12 @@ ACCOUNT_PORT_BASE=${ACCOUNT_PORT_BASE:-6012}

 SWIFT_ENABLE_TEMPURLS=${SWIFT_ENABLE_TEMPURLS:-False}

 SWIFT_TEMPURL_KEY=${SWIFT_TEMPURL_KEY:-}

+# Toggle for deploying Swift under HTTPD + mod_wsgi

+SWIFT_USE_MOD_WSGI=${SWIFT_USE_MOD_WSGI:-False}

+

 # Tell Tempest this project is present

 TEMPEST_SERVICES+=,swift

-# Toggle for deploying Swift under HTTPD + mod_wsgi

-SWIFT_USE_MOD_WSGI=${SWIFT_USE_MOD_WSGI:-False}

 # Functions

 # ---------

@@ -303,7 +303,6 @@ function generate_swift_config_services {

     sed -i -e "s,#[ ]*recon_cache_path .*,recon_cache_path = ${SWIFT_DATA_DIR}/cache," ${swift_node_config}

 }

-

 # configure_swift() - Set config files, create data dirs and loop image

 function configure_swift {

     local swift_pipeline="${SWIFT_EXTRAS_MIDDLEWARE_NO_AUTH}"

@@ -374,12 +373,9 @@ function configure_swift {

         iniset ${SWIFT_CONFIG_PROXY_SERVER} DEFAULT key_file "$SWIFT_SSL_KEY"

     fi

-    # Devstack is commonly run in a small slow environment, so bump the

-    # timeouts up.

-    # node_timeout is how long between read operations a node takes to

-    # respond to the proxy server

-    # conn_timeout is all about how long it takes a connect() system call to

-    # return

+    # DevStack is commonly run in a small slow environment, so bump the timeouts up.

+    # ``node_timeout`` is the node read operation response time to the proxy server

+    # ``conn_timeout`` is how long it takes a connect() system call to return

     iniset ${SWIFT_CONFIG_PROXY_SERVER} app:proxy-server node_timeout 120

     iniset ${SWIFT_CONFIG_PROXY_SERVER} app:proxy-server conn_timeout 20

@@ -394,10 +390,10 @@ function configure_swift {

         SWIFT_EXTRAS_MIDDLEWARE_LAST="${SWIFT_EXTRAS_MIDDLEWARE_LAST} ceilometer"

     fi

-    # Restrict the length of auth tokens in the swift proxy-server logs.

+    # Restrict the length of auth tokens in the Swift ``proxy-server`` logs.

     iniset ${SWIFT_CONFIG_PROXY_SERVER} filter:proxy-logging reveal_sensitive_prefix ${SWIFT_LOG_TOKEN_LENGTH}

-    # By default Swift will be installed with keystone and tempauth middleware

+    # By default Swift will be installed with Keystone and tempauth middleware

     # and add the swift3 middleware if its configured for it. The token for

     # tempauth would be prefixed with the reseller_prefix setting `TEMPAUTH_` the

     # token for keystoneauth would have the standard reseller_prefix `AUTH_`

@@ -413,17 +409,13 @@ function configure_swift {

     sed -i "/^pipeline/ { s/tempauth/${swift_pipeline} ${SWIFT_EXTRAS_MIDDLEWARE}/ ;}" ${SWIFT_CONFIG_PROXY_SERVER}

     sed -i "/^pipeline/ { s/proxy-server/${SWIFT_EXTRAS_MIDDLEWARE_LAST} proxy-server/ ; }" ${SWIFT_CONFIG_PROXY_SERVER}

-

     iniset ${SWIFT_CONFIG_PROXY_SERVER} app:proxy-server account_autocreate true

-

-

     # Configure Crossdomain

     iniset ${SWIFT_CONFIG_PROXY_SERVER} filter:crossdomain use "egg:swift#crossdomain"

-

-    # This causes the authtoken middleware to use the same python logging

-    # adapter provided by the swift proxy-server, so that request transaction

+    # Configure authtoken middleware to use the same Python logging

+    # adapter provided by the Swift ``proxy-server``, so that request transaction

     # IDs will included in all of its log messages.

     iniset ${SWIFT_CONFIG_PROXY_SERVER} filter:authtoken log_name swift

@@ -436,7 +428,7 @@ function configure_swift {

     iniset ${SWIFT_CONFIG_PROXY_SERVER} filter:keystoneauth use "egg:swift#keystoneauth"

     iniset ${SWIFT_CONFIG_PROXY_SERVER} filter:keystoneauth operator_roles "Member, admin"

-    # Configure Tempauth. In the sample config file, Keystoneauth is commented

+    # Configure Tempauth. In the sample config file Keystoneauth is commented

     # out. Make sure we uncomment Tempauth after we uncomment Keystoneauth

     # otherwise, this code also sets the reseller_prefix for Keystoneauth.

     iniuncomment ${SWIFT_CONFIG_PROXY_SERVER} filter:tempauth account_autocreate

@@ -579,7 +571,8 @@ function create_swift_disk {

         sudo chown -R ${STACK_USER}: ${node}

     done

 }

-# create_swift_accounts() - Set up standard swift accounts and extra

+

+# create_swift_accounts() - Set up standard Swift accounts and extra

 # one for tests we do this by attaching all words in the account name

 # since we want to make it compatible with tempauth which use

 # underscores for separators.

@@ -593,9 +586,9 @@ function create_swift_disk {

 # swifttenanttest4   swiftusertest4     admin          swift_test

 function create_swift_accounts {

-    # Defines specific passwords used by tools/create_userrc.sh

-    # As these variables are used by create_userrc.sh, they must be exported

-    # The _password suffix is expected by create_userrc.sh

+    # Defines specific passwords used by ``tools/create_userrc.sh``

+    # As these variables are used by ``create_userrc.sh,`` they must be exported

+    # The _password suffix is expected by ``create_userrc.sh``.

     export swiftusertest1_password=testing

     export swiftusertest2_password=testing2

     export swiftusertest3_password=testing3

@@ -725,8 +718,8 @@ function start_swift {

     # By default with only one replica we are launching the proxy,

     # container, account and object server in screen in foreground and

-    # other services in background. If we have SWIFT_REPLICAS set to something

-    # greater than one we first spawn all the swift services then kill the proxy

+    # other services in background. If we have ``SWIFT_REPLICAS`` set to something

+    # greater than one we first spawn all the Swift services then kill the proxy

     # service so we can run it in foreground in screen.  ``swift-init ...

     # {stop|restart}`` exits with '1' if no servers are running, ignore it just

     # in case

@@ -762,7 +755,7 @@ function stop_swift {

         swift-init --run-dir=${SWIFT_DATA_DIR}/run rest stop && return 0

     fi

-    # screen normally killed by unstack.sh

+    # screen normally killed by ``unstack.sh``

     if type -p swift-init >/dev/null; then

         swift-init --run-dir=${SWIFT_DATA_DIR}/run all stop || true

     fi

@@ -62,13 +62,11 @@ BUILD_INTERVAL=1

 # The default is set to 196 seconds.

 BUILD_TIMEOUT=${BUILD_TIMEOUT:-196}

-

 # This must be False on stable branches, as master tempest

 # deps do not match stable branch deps. Set this to True to

-# have tempest installed in devstack by default.

+# have tempest installed in DevStack by default.

 INSTALL_TEMPEST=${INSTALL_TEMPEST:-"True"}

-

 BOTO_MATERIALS_PATH="$FILES/images/s3-materials/cirros-${CIRROS_VERSION}"

 BOTO_CONF=/etc/boto.cfg

@@ -83,6 +81,7 @@ TEMPEST_STORAGE_PROTOCOL=${TEMPEST_STORAGE_PROTOCOL:-$TEMPEST_DEFAULT_STORAGE_PR

 IPV6_ENABLED=$(trueorfalse True IPV6_ENABLED)

 IPV6_SUBNET_ATTRIBUTES_ENABLED=$(trueorfalse True IPV6_SUBNET_ATTRIBUTES_ENABLED)

+

 # Functions

 # ---------

@@ -168,8 +167,8 @@ function configure_tempest {

         esac

     fi

-    # Create tempest.conf from tempest.conf.sample

-    # copy every time, because the image UUIDS are going to change

+    # Create ``tempest.conf`` from ``tempest.conf.sample``

+    # Copy every time because the image UUIDS are going to change

     sudo install -d -o $STACK_USER $TEMPEST_CONFIG_DIR

     install -m 644 $TEMPEST_DIR/etc/tempest.conf.sample $TEMPEST_CONFIG

@@ -179,8 +178,8 @@ function configure_tempest {

     # the cloud. We don't always want to so that we can ensure Tempest

     # would work on a public cloud.

     TEMPEST_HAS_ADMIN=$(trueorfalse True TEMPEST_HAS_ADMIN)

-    # See files/keystone_data.sh and stack.sh where admin, demo and alt_demo

-    # user and tenant are set up...

+

+    # See ``lib/keystone`` where these users and tenants are set up

     ADMIN_USERNAME=${ADMIN_USERNAME:-admin}

     ADMIN_TENANT_NAME=${ADMIN_TENANT_NAME:-admin}

     ADMIN_DOMAIN_NAME=${ADMIN_DOMAIN_NAME:-Default}

@@ -191,13 +190,13 @@ function configure_tempest {

     ADMIN_TENANT_ID=$(openstack project list | awk "/ admin / { print \$2 }")

     if is_service_enabled nova; then

-        # If the ``DEFAULT_INSTANCE_TYPE`` not declared, use the new behavior

-        # Tempest creates instane types for himself

+        # If ``DEFAULT_INSTANCE_TYPE`` is not declared, use the new behavior

+        # Tempest creates its own instance types

         if  [[ -z "$DEFAULT_INSTANCE_TYPE" ]]; then

             available_flavors=$(nova flavor-list)

             if [[ ! ( $available_flavors =~ 'm1.nano' ) ]]; then

                 if is_arch "ppc64"; then

-                    # qemu needs at least 128MB of memory to boot on ppc64

+                    # Qemu needs at least 128MB of memory to boot on ppc64

                     nova flavor-create m1.nano 42 128 0 1

                 else

                     nova flavor-create m1.nano 42 64 0 1

@@ -214,8 +213,7 @@ function configure_tempest {

             fi

             flavor_ref_alt=84

         else

-            # Check Nova for existing flavors and, if set, look for the

-            # ``DEFAULT_INSTANCE_TYPE`` and use that.

+            # Check Nova for existing flavors, if ``DEFAULT_INSTANCE_TYPE`` is set use it.

             boto_instance_type=$DEFAULT_INSTANCE_TYPE

             flavor_lines=`nova flavor-list`

             IFS=$'\r\n'

@@ -240,8 +238,8 @@ function configure_tempest {

             flavor_ref=${flavors[0]}

             flavor_ref_alt=$flavor_ref

-            # ensure flavor_ref and flavor_ref_alt have different values

-            # some resize instance in tempest tests depends on this.

+            # Ensure ``flavor_ref`` and ``flavor_ref_alt`` have different values.

+            # Some resize instance in tempest tests depends on this.

             for f in ${flavors[@]:1}; do

                 if [[ $f -ne $flavor_ref ]]; then

                     flavor_ref_alt=$f

@@ -266,7 +264,7 @@ function configure_tempest {

         public_network_id=$(neutron net-list | grep $PUBLIC_NETWORK_NAME | \

             awk '{print $2}')

         if [ "$Q_USE_NAMESPACE" == "False" ]; then

-            # If namespaces are disabled, devstack will create a single

+            # If namespaces are disabled, DevStack will create a single

             # public router that tempest should be configured to use.

             public_router_id=$(neutron router-list | awk "/ $Q_ROUTER_NAME / \

                 { print \$2 }")

@@ -274,6 +272,7 @@ function configure_tempest {

     fi

     iniset $TEMPEST_CONFIG DEFAULT use_syslog $SYSLOG

+

     # Oslo

     iniset $TEMPEST_CONFIG oslo_concurrency lock_path $TEMPEST_STATE_PATH

     mkdir -p $TEMPEST_STATE_PATH

@@ -309,15 +308,13 @@ function configure_tempest {

     fi

     # Image

-    # for the gate we want to be able to override this variable so we aren't

-    # doing an HTTP fetch over the wide internet for this test

+    # We want to be able to override this variable in the gate to avoid

+    # doing an external HTTP fetch for this test.

     if [[ ! -z "$TEMPEST_HTTP_IMAGE" ]]; then

         iniset $TEMPEST_CONFIG image http_image $TEMPEST_HTTP_IMAGE

     fi

     # Auth

-    #

-    #

     TEMPEST_ALLOW_TENANT_ISOLATION=${TEMPEST_ALLOW_TENANT_ISOLATION:-$TEMPEST_HAS_ADMIN}

     iniset $TEMPEST_CONFIG auth allow_tenant_isolation ${TEMPEST_ALLOW_TENANT_ISOLATION:-True}

     iniset $TEMPEST_CONFIG auth tempest_roles "Member"

@@ -336,7 +333,7 @@ function configure_tempest {

     iniset $TEMPEST_CONFIG compute ssh_connect_method $ssh_connect_method

     # Compute Features

-    # Run verify_tempest_config -ur to retrieve enabled extensions on API endpoints

+    # Run ``verify_tempest_config -ur`` to retrieve enabled extensions on API endpoints

     # NOTE(mtreinish): This must be done after auth settings are added to the tempest config

     local tmp_cfg_file=$(mktemp)

     cd $TEMPEST_DIR

@@ -417,11 +414,11 @@ function configure_tempest {

     iniset $TEMPEST_CONFIG scenario large_ops_number ${TEMPEST_LARGE_OPS_NUMBER:-0}

     # Telemetry

-    # Ceilometer API optimization happened in juno that allows to run more tests in tempest.

+    # Ceilometer API optimization happened in Juno that allows to run more tests in tempest.

     # Once Tempest retires support for icehouse this flag can be removed.

     iniset $TEMPEST_CONFIG telemetry too_slow_to_test "False"

-    # Object storage

+    # Object Store

     local object_storage_api_extensions=${OBJECT_STORAGE_API_EXTENSIONS:-"all"}

     if [[ ! -z "$DISABLE_OBJECT_STORAGE_API_EXTENSIONS" ]]; then

         # Enabled extensions are either the ones explicitly specified or those available on the API endpoint

@@ -445,7 +442,7 @@ function configure_tempest {

         iniset $TEMPEST_CONFIG volume-feature-enabled backup False

     fi

-    # Using CINDER_ENABLED_BACKENDS

+    # Using ``CINDER_ENABLED_BACKENDS``

     if [[ -n "$CINDER_ENABLED_BACKENDS" ]] && [[ $CINDER_ENABLED_BACKENDS =~ .*,.* ]]; then

         iniset $TEMPEST_CONFIG volume-feature-enabled multi_backend "True"

         local i=1

@@ -470,7 +467,7 @@ function configure_tempest {

     iniset $TEMPEST_CONFIG dashboard dashboard_url "http://$SERVICE_HOST/"

     iniset $TEMPEST_CONFIG dashboard login_url "http://$SERVICE_HOST/auth/login/"

-    # cli

+    # CLI

     iniset $TEMPEST_CONFIG cli cli_dir $NOVA_BIN_DIR

     # Baremetal

@@ -495,7 +492,7 @@ function configure_tempest {

         iniset $TEMPEST_CONFIG compute-feature-enabled suspend False

     fi

-    # service_available

+    # ``service_available``

     for service in ${TEMPEST_SERVICES//,/ }; do

         if is_service_enabled $service ; then

             iniset $TEMPEST_CONFIG service_available $service "True"

@@ -505,7 +502,7 @@ function configure_tempest {

     done

     if is_ssl_enabled_service "key" || is_service_enabled tls-proxy; then

-        # Use the BOTO_CONFIG environment variable to point to this file

+        # Use the ``BOTO_CONFIG`` environment variable to point to this file

         iniset $BOTO_CONF Boto ca_certificates_file $SSL_BUNDLE_FILE

         sudo chown $STACK_USER $BOTO_CONF

     fi

@@ -520,7 +517,6 @@ function configure_tempest {

 # ------------------------------------------------------------------

 # alt_demo             alt_demo     Member

-# Migrated from keystone_data.sh

 function create_tempest_accounts {

     if is_service_enabled tempest; then

         # Tempest has some tests that validate various authorization checks

@@ -531,13 +527,13 @@ function create_tempest_accounts {

     fi

 }

-# install_tempest_lib() - Collect source, prepare, and install tempest-lib

+# install_tempest_lib() - Collect source, prepare, and install ``tempest-lib``

 function install_tempest_lib {

     if use_library_from_git "tempest-lib"; then

         git_clone_by_name "tempest-lib"

         setup_dev_lib "tempest-lib"

-        # NOTE(mtreinish) For testing tempest-lib from git with tempest we need

-        # put the git version of tempest-lib in the tempest job's tox venv

+        # NOTE(mtreinish) For testing ``tempest-lib`` from git with Tempest we need to

+        # put the git version of ``tempest-lib`` in the Tempest job's tox venv

         export PIP_VIRTUAL_ENV=${PROJECT_VENV["tempest"]}

         setup_dev_lib "tempest-lib"

         unset PIP_VIRTUAL_ENV

@@ -555,7 +551,7 @@ function install_tempest {

     popd

 }

-# init_tempest() - Initialize ec2 images

+# init_tempest() - Initialize EC2 images

 function init_tempest {

     local base_image_name=cirros-${CIRROS_VERSION}-${CIRROS_ARCH}

     # /opt/stack/devstack/files/images/cirros-${CIRROS_VERSION}-${CIRROS_ARCH}-uec

@@ -564,7 +560,7 @@ function init_tempest {

     local ramdisk="$image_dir/${base_image_name}-initrd"

     local disk_image="$image_dir/${base_image_name}-blank.img"

     if is_service_enabled nova; then

-        # if the cirros uec downloaded and the system is uec capable

+        # If the CirrOS uec downloaded and the system is UEC capable

         if [ -f "$kernel" -a -f "$ramdisk" -a -f "$disk_image" -a  "$VIRT_DRIVER" != "openvz" \

             -a \( "$LIBVIRT_TYPE" != "lxc" -o "$VIRT_DRIVER" != "libvirt" \) ]; then

             echo "Prepare aki/ari/ami Images"

@@ -32,6 +32,7 @@

 # - is_ssl_enabled_service

 # - enable_mod_ssl

+

 # Defaults

 # --------

@@ -92,7 +93,6 @@ function create_CA_base {

     cp /dev/null $ca_dir/index.txt

 }

-

 # Create a new CA configuration file

 # create_CA_config ca-dir common-name

 function create_CA_config {

@@ -248,7 +248,6 @@ function init_cert {

     fi

 }

-

 # make_cert creates and signs a new certificate with the given commonName and CA

 # make_cert ca-dir cert-name "common-name" ["alt-name" ...]

 function make_cert {

@@ -287,7 +286,6 @@ function make_cert {

     fi

 }

-

 # Make an intermediate CA to sign everything else

 # make_int_CA ca-dir signing-ca-dir

 function make_int_CA {

@@ -362,17 +360,16 @@ function is_ssl_enabled_service {

     return 1

 }

-

 # Ensure that the certificates for a service are in place. This function does

 # not check that a service is SSL enabled, this should already have been

 # completed.

 #

 # The function expects to find a certificate, key and CA certificate in the

-# variables {service}_SSL_CERT, {service}_SSL_KEY and {service}_SSL_CA. For

-# example for keystone this would be KEYSTONE_SSL_CERT, KEYSTONE_SSL_KEY and

-# KEYSTONE_SSL_CA.

+# variables ``{service}_SSL_CERT``, ``{service}_SSL_KEY`` and ``{service}_SSL_CA``. For

+# example for keystone this would be ``KEYSTONE_SSL_CERT``, ``KEYSTONE_SSL_KEY`` and

+# ``KEYSTONE_SSL_CA``.

 #

-# If it does not find these certificates then the devstack-issued server

+# If it does not find these certificates then the DevStack-issued server

 # certificate, key and CA certificate will be associated with the service.

 #

 # If only some of the variables are provided then the function will quit.

@@ -437,14 +434,12 @@ function start_tls_proxy {

 # Cleanup Functions

 # =================

-

 # Stops all stud processes. This should be done only after all services

 # using tls configuration are down.

 function stop_tls_proxy {

     killall stud

 }

-

 # Remove CA along with configuration, as well as the local server certificate

 function cleanup_CA {

     rm -rf "$DATA_DIR/CA" "$DEVSTACK_CERT"

@@ -21,6 +21,7 @@

 XTRACE=$(set +o | grep xtrace)

 set +o xtrace

+

 # Defaults

 # --------

 if is_service_enabled neutron; then

@@ -80,7 +81,7 @@ function setup_trove_logging {

     fi

 }

-# create_trove_accounts() - Set up common required trove accounts

+# create_trove_accounts() - Set up common required Trove accounts

 # Tenant               User       Roles

 # ------------------------------------------------------------------

@@ -115,7 +116,6 @@ function cleanup_trove {

     rm -fr $TROVE_CONF_DIR/*

 }

-

 # configure_trove() - Set config files, create data dirs, etc

 function configure_trove {

     setup_develop $TROVE_DIR

@@ -11,9 +11,8 @@

 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the

 # License for the specific language governing permissions and limitations

 # under the License.

-#

-#

-# this runs a series of unit tests for devstack to ensure it's functioning

+

+# This runs a series of unit tests for DevStack to ensure it's functioning

 PASSES=""

 FAILURES=""

@@ -1,7 +1,6 @@

 # Sample ``local.conf`` for user-configurable variables in ``stack.sh``

-# NOTE: Copy this file to the root ``devstack`` directory for it to

-# work properly.

+# NOTE: Copy this file to the root DevStack directory for it to work properly.

 # ``local.conf`` is a user-maintained settings file that is sourced from ``stackrc``.

 # This gives it the ability to override any variables set in ``stackrc``.

@@ -3,15 +3,14 @@

 # Sample ``local.sh`` for user-configurable tasks to run automatically

 # at the successful conclusion of ``stack.sh``.

-# NOTE: Copy this file to the root ``devstack`` directory for it to

-# work properly.

+# NOTE: Copy this file to the root DevStack directory for it to work properly.

 # This is a collection of some of the things we have found to be useful to run

 # after ``stack.sh`` to tweak the OpenStack configuration that DevStack produces.

 # These should be considered as samples and are unsupported DevStack code.