@@ -1,7 +1,16 @@

-# -*- mode: Shell-script -*-

 # functions - Common functions used by DevStack components

 #

-# ENABLED_SERVICES is used by is_service_enabled()

+# The following variables are assumed to be defined by certain functions:

+# ``DISTRO``

+# ``ENABLED_SERVICES``

+# ``EROR_ON_CLONE``

+# ``FILES``

+# ``GLANCE_HOSTPORT``

+# ``OFFLINE``

+# ``PIP_DOWNLOAD_CACHE``

+# ``RECLONE``

+# ``TRACK_DEPENDS``

+# ``http_proxy``, ``https_proxy``, ``no_proxy``

 # Save trace setting

@@ -9,9 +18,9 @@ XTRACE=$(set +o | grep xtrace)

 set +o xtrace

-# Exit 0 if address is in network or 1 if

-# address is not in network or netaddr library

-# is not installed.

+# Exit 0 if address is in network or 1 if address is not in

+# network or netaddr library is not installed.

+# address_in_net ip-address ip-range

 function address_in_net() {

     python -c "

 import netaddr

@@ -21,7 +30,8 @@ sys.exit(netaddr.IPAddress('$1') not in netaddr.IPNetwork('$2'))

 }

-# apt-get wrapper to set arguments correctly

+# Wrapper for ``apt-get`` to set cache and proxy environment variables

+# Uses globals ``OFFLINE``, ``*_proxy`

 # apt_get operation package [package ...]

 function apt_get() {

     [[ "$OFFLINE" = "True" || -z "$@" ]] && return

@@ -88,15 +98,16 @@ function get_field() {

 # get_packages() collects a list of package names of any type from the

-# prerequisite files in ``files/{apts|pips}``.  The list is intended

-# to be passed to a package installer such as apt or pip.

+# prerequisite files in ``files/{apts|rpms}``.  The list is intended

+# to be passed to a package installer such as apt or yum.

 #

-# Only packages required for the services in ENABLED_SERVICES will be

+# Only packages required for the services in ``ENABLED_SERVICES`` will be

 # included.  Two bits of metadata are recognized in the prerequisite files:

 # - ``# NOPRIME`` defers installation to be performed later in stack.sh

 # - ``# dist:DISTRO`` or ``dist:DISTRO1,DISTRO2`` limits the selection

 #   of the package to the distros listed.  The distro names are case insensitive.

 #

+# Uses globals ``DISTRO``, ``ENABLED_SERVICES``

 # get_packages dir

 function get_packages() {

     local package_dir=$1

@@ -241,6 +252,7 @@ GetOSVersion() {

 }

 # git update using reference as a branch.

+# git_update_branch ref

 function git_update_branch() {

     GIT_BRANCH=$1

@@ -254,6 +266,7 @@ function git_update_branch() {

 # git update using reference as a tag. Be careful editing source at that repo

 # as working copy will be in a detached mode

+# git_update_tag ref

 function git_update_tag() {

     GIT_TAG=$1

@@ -289,6 +302,7 @@ function GetDistro() {

 # Set global RECLONE=yes to simulate a clone when dest-dir exists

 # Set global ERROR_ON_CLONE=True to abort execution with an error if the git repo

 # does not exist (default is False, meaning the repo will be cloned).

+# Uses global ``OFFLINE``

 # git_clone remote dest-dir branch

 function git_clone {

     [[ "$OFFLINE" = "True" ]] && return

@@ -394,16 +408,20 @@ $option = $value

 # is_service_enabled() checks if the service(s) specified as arguments are

-# enabled by the user in **ENABLED_SERVICES**.

+# enabled by the user in ``ENABLED_SERVICES``.

 #

-# If there are multiple services specified as arguments the test performs a

-# boolean OR or if any of the services specified on the command line

-# return true.

+# Multiple services specified as arguments are ``OR``'ed together; the test

+# is a short-circuit boolean, i.e it returns on the first match.

 #

-# There is a special cases for some 'catch-all' services::

+# There are special cases for some 'catch-all' services::

 #   **nova** returns true if any service enabled start with **n-**

+#   **cinder** returns true if any service enabled start with **c-**

+#   **ceilometer** returns true if any service enabled start with **ceilometer**

 #   **glance** returns true if any service enabled start with **g-**

 #   **quantum** returns true if any service enabled start with **q-**

+#

+# Uses global ``ENABLED_SERVICES``

+# is_service_enabled service [service ...]

 function is_service_enabled() {

     services=$@

     for service in ${services}; do

@@ -417,7 +435,9 @@ function is_service_enabled() {

     return 1

 }

-# remove extra commas from the input string (ENABLED_SERVICES)

+

+# remove extra commas from the input string (i.e. ``ENABLED_SERVICES``)

+# _cleanup_service_list service-list

 function _cleanup_service_list () {

     echo "$1" | sed -e '

         s/,,/,/g;

@@ -426,15 +446,17 @@ function _cleanup_service_list () {

     '

 }

+

 # enable_service() adds the services passed as argument to the

-# **ENABLED_SERVICES** list, if they are not already present.

+# ``ENABLED_SERVICES`` list, if they are not already present.

 #

 # For example:

-#

 #   enable_service n-vol

 #

 # This function does not know about the special cases

 # for nova, glance, and quantum built into is_service_enabled().

+# Uses global ``ENABLED_SERVICES``

+# enable_service service [service ...]

 function enable_service() {

     local tmpsvcs="${ENABLED_SERVICES}"

     for service in $@; do

@@ -446,15 +468,17 @@ function enable_service() {

     disable_negated_services

 }

+

 # disable_service() removes the services passed as argument to the

-# **ENABLED_SERVICES** list, if they are present.

+# ``ENABLED_SERVICES`` list, if they are present.

 #

 # For example:

-#

 #   disable_service n-vol

 #

 # This function does not know about the special cases

 # for nova, glance, and quantum built into is_service_enabled().

+# Uses global ``ENABLED_SERVICES``

+# disable_service service [service ...]

 function disable_service() {

     local tmpsvcs=",${ENABLED_SERVICES},"

     local service

@@ -466,17 +490,22 @@ function disable_service() {

     ENABLED_SERVICES=$(_cleanup_service_list "$tmpsvcs")

 }

+

 # disable_all_services() removes all current services

-# from **ENABLED_SERVICES** to reset the configuration

+# from ``ENABLED_SERVICES`` to reset the configuration

 # before a minimal installation

+# Uses global ``ENABLED_SERVICES``

+# disable_all_services

 function disable_all_services() {

     ENABLED_SERVICES=""

 }

-# We are looking for services with a - at the beginning to force

-# excluding those services. For example if you want to install all the default

-# services but not nova-volume (n-vol) you can have this set in your localrc :

+

+# Remove all services starting with '-'.  For example, to install all default

+# services except nova-volume (n-vol) set in ``localrc``:

 # ENABLED_SERVICES+=",-n-vol"

+# Uses global ``ENABLED_SERVICES``

+# disable_negated_services

 function disable_negated_services() {

     local tmpsvcs="${ENABLED_SERVICES}"

     local service

@@ -488,6 +517,7 @@ function disable_negated_services() {

     ENABLED_SERVICES=$(_cleanup_service_list "$tmpsvcs")

 }

+

 # Distro-agnostic package installer

 # install_package package [package ...]

 function install_package() {

@@ -513,7 +543,8 @@ function is_set() {

 }

-# pip install wrapper to set cache and proxy environment variables

+# Wrapper for ``pip install`` to set cache and proxy environment variables

+# Uses globals ``OFFLINE``, ``PIP_DOWNLOAD_CACHE``, ``TRACK_DEPENDES``, ``*_proxy`

 # pip_install package [package ...]

 function pip_install {

     [[ "$OFFLINE" = "True" || -z "$@" ]] && return

@@ -554,8 +585,9 @@ function restart_service() {

 }

-# pip install the dependencies of the package before we do the setup.py

-# develop, so that pip and not distutils process the dependency chain

+# ``pip install`` the dependencies of the package before ``setup.py develop``

+# so pip and not distutils processes the dependency chain

+# Uses globals ``TRACK_DEPENDES``, ``*_proxy`

 # setup_develop directory

 function setup_develop() {

     if [[ $TRACK_DEPENDS = True ]] ; then

@@ -606,7 +638,9 @@ function stop_service() {

 # Normalize config values to True or False

-# VAR=`trueorfalse default-value test-value`

+# Accepts as False: 0 no false False FALSE

+# Accepts as True: 1 yes true True TRUE

+# VAR=$(trueorfalse default-value test-value)

 function trueorfalse() {

     local default=$1

     local testval=$2

@@ -620,8 +654,8 @@ function trueorfalse() {

 # Retrieve an image from a URL and upload into Glance

 # Uses the following variables:

-#   **FILES** must be set to the cache dir

-#   **GLANCE_HOSTPORT**

+#   ``FILES`` must be set to the cache dir

+#   ``GLANCE_HOSTPORT``

 # upload_image image-url glance-token

 function upload_image() {

     local image_url=$1

@@ -717,7 +751,8 @@ function upload_image() {

 }

-# yum wrapper to set arguments correctly

+# Wrapper for ``yum`` to set proxy environment variables

+# Uses globals ``OFFLINE``, ``*_proxy`

 # yum_install package [package ...]

 function yum_install() {

     [[ "$OFFLINE" = "True" ]] && return

@@ -731,3 +766,8 @@ function yum_install() {

 # Restore xtrace

 $XTRACE

+

+

+# Local variables:

+# -*- mode: Shell-script -*-

+# End:

\ No newline at end of file

@@ -1,8 +1,9 @@

 #!/usr/bin/env bash

 # ``stack.sh`` is an opinionated OpenStack developer installation.  It

-# installs and configures various combinations of **Glance**, **Horizon**,

-# **Keystone**, **Nova**, **Quantum**, **Heat** and **Swift**

+# installs and configures various combinations of **Ceilometer**, **Cinder**,

+# **Glance**, **Heat**, **Horizon**, **Keystone**, **Nova**, **Quantum**

+# and **Swift**

 # This script allows you to specify configuration options of what git

 # repositories to use, enabled services, network configuration and various

@@ -10,14 +11,14 @@

 # shared settings for common resources (mysql, rabbitmq) and build a multi-node

 # developer install.

-# To keep this script simple we assume you are running on an **Ubuntu 11.10

-# Oneiric** or **Ubuntu 12.04 Precise** machine.  It should work in a VM or

-# physical server.  Additionally we put the list of ``apt`` and ``pip``

-# dependencies and other configuration files in this repo.  So start by

-# grabbing this script and the dependencies.

+# To keep this script simple we assume you are running on a recent **Ubuntu**

+# (11.10 Oneiric or 12.04 Precise) or **Fedora** (F16 or F17) machine.  It

+# should work in a VM or physical server.  Additionally we put the list of

+# ``apt`` and ``rpm`` dependencies and other configuration files in this repo.

 # Learn more and get the most recent version at http://devstack.org

+

 # Keep track of the devstack directory

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

@@ -47,25 +48,31 @@ GetDistro

 #     MYSQL_USER=hellaroot

 #

 # We try to have sensible defaults, so you should be able to run ``./stack.sh``

-# in most cases.

+# in most cases.  ``localrc`` is not distributed with DevStack and will never

+# be overwritten by a DevStack update.

 #

 # DevStack distributes ``stackrc`` which contains locations for the OpenStack

 # repositories and branches to configure.  ``stackrc`` sources ``localrc`` to

-# allow you to safely override those settings without being overwritten

-# when updating DevStack.

+# allow you to safely override those settings.

+

 if [[ ! -r $TOP_DIR/stackrc ]]; then

     echo "ERROR: missing $TOP_DIR/stackrc - did you grab more than just stack.sh?"

     exit 1

 fi

 source $TOP_DIR/stackrc

-# HTTP and HTTPS proxy servers are supported via the usual environment variables

-# ``http_proxy`` and ``https_proxy``.  Additionally if you would like to access

-# to specific server directly and not through the proxy server, you can use

-# ``no_proxy`` environment variable.  They can be set in ``localrc`` if necessary

-# or on the command line::

+

+# Proxy Settings

+# --------------

+

+# HTTP and HTTPS proxy servers are supported via the usual environment variables [1]

+# ``http_proxy``, ``https_proxy`` and ``no_proxy``. They can be set in

+# ``localrc`` if necessary or on the command line::

+#

+# [1] http://www.w3.org/Daemon/User/Proxies/ProxyClients.html

 #

 #     http_proxy=http://proxy.example.com:3128/ no_proxy=repo.example.net ./stack.sh

+

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

     export http_proxy=$http_proxy

 fi

@@ -98,6 +105,7 @@ if [[ ! ${DISTRO} =~ (oneiric|precise|quantal|f16|f17) ]]; then

     fi

 fi

+# Disallow qpid on oneiric

 if [ "${DISTRO}" = "oneiric" ] && is_service_enabled qpid ; then

     # Qpid was introduced in precise

     echo "You must use Ubuntu Precise or newer for Qpid support."

@@ -114,17 +122,15 @@ fi

 # ``stack.sh`` keeps function libraries here

 # Make sure ``$TOP_DIR/lib`` directory is present

 if [ ! -d $TOP_DIR/lib ]; then

-    echo "ERROR: missing devstack/lib - did you grab more than just stack.sh?"

+    echo "ERROR: missing devstack/lib"

     exit 1

 fi

-# stack.sh keeps the list of ``apt`` and ``pip`` dependencies in external

-# files, along with config templates and other useful files.  You can find these

-# in the ``files`` directory (next to this script).  We will reference this

-# directory using the ``FILES`` variable in this script.

+# ``stack.sh`` keeps the list of ``apt`` and ``rpm`` dependencies and config

+# templates and other useful files in the ``files`` subdirectory

 FILES=$TOP_DIR/files

 if [ ! -d $FILES ]; then

-    echo "ERROR: missing devstack/files - did you grab more than just stack.sh?"

+    echo "ERROR: missing devstack/files"

     exit 1

 fi

@@ -132,7 +138,7 @@ fi

 if type -p screen >/dev/null && screen -ls | egrep -q "[0-9].stack"; then

     echo "You are already running a stack.sh session."

     echo "To rejoin this session type 'screen -x stack'."

-    echo "To destroy this session, kill the running screen."

+    echo "To destroy this session, type './unstack.sh'."

     exit 1

 fi

@@ -142,8 +148,12 @@ if is_service_enabled cinder && is_service_enabled n-vol; then

     exit 1

 fi

-# OpenStack is designed to be run as a regular user (Horizon will fail to run

-# as root, since apache refused to startup serve content from root user).  If

+

+# root Access

+# -----------

+

+# OpenStack is designed to be run as a non-root user; Horizon will fail to run

+# as **root** since Apache will not serve content from **root** user).  If

 # ``stack.sh`` is run as **root**, it automatically creates a **stack** user with

 # sudo privileges and runs as that user.

@@ -153,8 +163,7 @@ if [[ $EUID -eq 0 ]]; then

     echo "In $ROOTSLEEP seconds, we will create a user 'stack' and run as that user"

     sleep $ROOTSLEEP

-    # since this script runs as a normal user, we need to give that user

-    # ability to run sudo

+    # Give the non-root user the ability to run as **root** via ``sudo``

     if [[ "$os_PACKAGE" = "deb" ]]; then

         dpkg -l sudo || apt_get update && install_package sudo

     else

@@ -170,7 +179,7 @@ if [[ $EUID -eq 0 ]]; then

     fi

     echo "Giving stack user passwordless sudo priviledges"

-    # some uec images sudoers does not have a '#includedir'. add one.

+    # UEC images ``/etc/sudoers`` does not have a ``#includedir``, add one

     grep -q "^#includedir.*/etc/sudoers.d" /etc/sudoers ||

         echo "#includedir /etc/sudoers.d" >> /etc/sudoers

     ( umask 226 && echo "stack ALL=(ALL) NOPASSWD:ALL" \

@@ -187,7 +196,7 @@ if [[ $EUID -eq 0 ]]; then

     fi

     exit 1

 else

-    # We're not root, make sure sudo is available

+    # We're not **root**, make sure ``sudo`` is available

     if [[ "$os_PACKAGE" = "deb" ]]; then

         CHECK_SUDO_CMD="dpkg -l sudo"

     else

@@ -195,7 +204,7 @@ else

     fi

     $CHECK_SUDO_CMD || die "Sudo is required.  Re-run stack.sh as root ONE TIME ONLY to set up sudo."

-    # UEC images /etc/sudoers does not have a '#includedir'. add one.

+    # UEC images ``/etc/sudoers`` does not have a ``#includedir``, add one

     sudo grep -q "^#includedir.*/etc/sudoers.d" /etc/sudoers ||

         echo "#includedir /etc/sudoers.d" | sudo tee -a /etc/sudoers

@@ -219,14 +228,14 @@ if [ ! -w $DEST ]; then

     sudo chown `whoami` $DEST

 fi

-# Set True to configure ``stack.sh`` to run cleanly without Internet access.

-# ``stack.sh`` must have been previously run with Internet access to install

-# prerequisites and initialize ``$DEST``.

+# Set ``OFFLINE`` to ``True`` to configure ``stack.sh`` to run cleanly without

+# Internet access. ``stack.sh`` must have been previously run with Internet

+# access to install prerequisites and fetch repositories.

 OFFLINE=`trueorfalse False $OFFLINE`

-# Set True to configure ``stack.sh`` to exit with an error code if it is asked

-# to clone any git repositories.  If devstack is used in a testing environment,

-# this may be used to ensure that the correct code is being tested.

+# Set ``ERROR_ON_CLONE`` to ``True`` to configure ``stack.sh`` to exit if

+# the destination git repository does not exist during the ``git_clone``

+# operation.

 ERROR_ON_CLONE=`trueorfalse False $ERROR_ON_CLONE`

 # Destination path for service data

@@ -235,15 +244,15 @@ sudo mkdir -p $DATA_DIR

 sudo chown `whoami` $DATA_DIR

-# Projects

-# --------

+# Configure Projects

+# ==================

 # Get project function libraries

 source $TOP_DIR/lib/cinder

 source $TOP_DIR/lib/ceilometer

 source $TOP_DIR/lib/heat

-# Set the destination directories for openstack projects

+# Set the destination directories for OpenStack projects

 NOVA_DIR=$DEST/nova

 HORIZON_DIR=$DEST/horizon

 GLANCE_DIR=$DEST/glance

@@ -273,17 +282,19 @@ Q_AUTH_STRATEGY=${Q_AUTH_STRATEGY:-keystone}

 # Use namespace or not

 Q_USE_NAMESPACE=${Q_USE_NAMESPACE:-True}

-# Name of the lvm volume group to use/create for iscsi volumes

+# Name of the LVM volume group to use/create for iscsi volumes

 VOLUME_GROUP=${VOLUME_GROUP:-stack-volumes}

 VOLUME_NAME_PREFIX=${VOLUME_NAME_PREFIX:-volume-}

 INSTANCE_NAME_PREFIX=${INSTANCE_NAME_PREFIX:-instance-}

-# Nova supports pluggable schedulers.  ``FilterScheduler`` should work in most

-# cases.

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

+# should work in most cases.

 SCHEDULER=${SCHEDULER:-nova.scheduler.filter_scheduler.FilterScheduler}

 # Set fixed and floating range here so we can make sure not to use addresses

-# from either range when attempting to guess the ip to use for the host

+# from either range when attempting to guess the IP to use for the host.

+# Note that setting FIXED_RANGE may be necessary when running DevStack

+# in an OpenStack cloud that uses eith of these address ranges internally.

 FIXED_RANGE=${FIXED_RANGE:-10.0.0.0/24}

 FLOATING_RANGE=${FLOATING_RANGE:-172.24.4.224/28}

@@ -294,10 +305,12 @@ if [ -z "$HOST_IP" -o "$HOST_IP" == "dhcp" ]; then

     HOST_IP=""

     HOST_IPS=`LC_ALL=C ip -f inet addr show ${HOST_IP_IFACE} | awk '/inet/ {split($2,parts,"/");  print parts[1]}'`

     for IP in $HOST_IPS; do

-        # Attempt to filter out ip addresses that are part of the fixed and

-        # floating range. Note that this method only works if the 'netaddr'

+        # Attempt to filter out IP addresses that are part of the fixed and

+        # floating range. Note that this method only works if the ``netaddr``

         # python library is installed. If it is not installed, an error

-        # will be printed and the first ip from the interface will be used.

+        # will be printed and the first IP from the interface will be used.

+        # If that is not correct set ``HOST_IP`` in ``localrc`` to the correct

+        # address.

         if ! (address_in_net $IP $FIXED_RANGE || address_in_net $IP $FLOATING_RANGE); then

             HOST_IP=$IP

             break;

@@ -318,7 +331,7 @@ SYSLOG=`trueorfalse False $SYSLOG`

 SYSLOG_HOST=${SYSLOG_HOST:-$HOST_IP}

 SYSLOG_PORT=${SYSLOG_PORT:-516}

-# Use color for logging output

+# Use color for logging output (only available if syslog is not used)

 LOG_COLOR=`trueorfalse True $LOG_COLOR`

 # Service startup timeout

@@ -374,7 +387,7 @@ function read_password {

 if [ "$VIRT_DRIVER" = 'xenserver' ]; then

     PUBLIC_INTERFACE_DEFAULT=eth3

-    # allow build_domU.sh to specify the flat network bridge via kernel args

+    # Allow ``build_domU.sh`` to specify the flat network bridge via kernel args

     FLAT_NETWORK_BRIDGE_DEFAULT=$(grep -o 'flat_network_bridge=[[:alnum:]]*' /proc/cmdline | cut -d= -f 2 | sort -u)

     GUEST_INTERFACE_DEFAULT=eth1

 else

@@ -396,19 +409,19 @@ VLAN_INTERFACE=${VLAN_INTERFACE:-$GUEST_INTERFACE_DEFAULT}

 TEST_FLOATING_POOL=${TEST_FLOATING_POOL:-test}

 TEST_FLOATING_RANGE=${TEST_FLOATING_RANGE:-192.168.253.0/29}

-# **MULTI_HOST** is a mode where each compute node runs its own network node.  This

+# ``MULTI_HOST`` is a mode where each compute node runs its own network node.  This

 # allows network operations and routing for a VM to occur on the server that is

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

 MULTI_HOST=`trueorfalse False $MULTI_HOST`

-# If you are using FlatDHCP on multiple hosts, set the ``FLAT_INTERFACE``

-# variable but make sure that the interface doesn't already have an

-# ip or you risk breaking things.

+# If you are using the FlatDHCP network mode on multiple hosts, set the

+# ``FLAT_INTERFACE`` variable but make sure that the interface doesn't already

+# have an IP or you risk breaking things.

 #

 # **DHCP Warning**:  If your flat interface device uses DHCP, there will be a

 # hiccup while the network is moved from the flat interface to the flat network

 # bridge.  This will happen when you launch your first instance.  Upon launch

-# you will lose all connectivity to the node, and the vm launch will probably

+# you will lose all connectivity to the node, and the VM launch will probably

 # fail.

 #

 # If you are running on a single node and don't need to access the VMs from

@@ -431,6 +444,7 @@ FLAT_INTERFACE=${FLAT_INTERFACE:-$GUEST_INTERFACE_DEFAULT}

 #

 # With Quantum networking the NET_MAN variable is ignored.

+

 # MySQL & (RabbitMQ or Qpid)

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

@@ -446,7 +460,7 @@ MYSQL_HOST=${MYSQL_HOST:-localhost}

 MYSQL_USER=${MYSQL_USER:-root}

 read_password MYSQL_PASSWORD "ENTER A PASSWORD TO USE FOR MYSQL."

-# NOTE: Don't specify /db in this string so we can use it for multiple services

+# NOTE: Don't specify ``/db`` in this string so we can use it for multiple services

 BASE_SQL_CONN=${BASE_SQL_CONN:-mysql://$MYSQL_USER:$MYSQL_PASSWORD@$MYSQL_HOST}

 # Rabbit connection info

@@ -455,6 +469,10 @@ if is_service_enabled rabbit; then

     read_password RABBIT_PASSWORD "ENTER A PASSWORD TO USE FOR RABBIT."

 fi

+

+# Glance

+# ------

+

 # Glance connection info.  Note the port must be specified.

 GLANCE_HOSTPORT=${GLANCE_HOSTPORT:-$SERVICE_HOST:9292}

@@ -464,19 +482,17 @@ GLANCE_HOSTPORT=${GLANCE_HOSTPORT:-$SERVICE_HOST:9292}

 # TODO: add logging to different location.

-# By default the location of swift drives and objects is located inside

-# the swift source directory. SWIFT_DATA_DIR variable allow you to redefine

-# this.

+# Set ``SWIFT_DATA_DIR`` to the location of swift drives and objects.

+# Default is the common DevStack data directory.

 SWIFT_DATA_DIR=${SWIFT_DATA_DIR:-${DEST}/data/swift}

-# We are going to have the configuration files inside the source

-# directory, change SWIFT_CONFIG_DIR if you want to adjust that.

+# Set ``SWIFT_CONFIG_DIR`` to the location of the configuration files.

+# Default is ``/etc/swift``.

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

 # DevStack will create a loop-back disk formatted as XFS to store the

-# swift data. By default the disk size is 1 gigabyte. The variable

-# SWIFT_LOOPBACK_DISK_SIZE specified in bytes allow you to change

-# that.

+# swift data. Set ``SWIFT_LOOPBACK_DISK_SIZE`` to the disk size in bytes.

+# Default is 1 gigabyte.

 SWIFT_LOOPBACK_DISK_SIZE=${SWIFT_LOOPBACK_DISK_SIZE:-1000000}

 # The ring uses a configurable number of bits from a path’s MD5 hash as

@@ -489,7 +505,7 @@ SWIFT_LOOPBACK_DISK_SIZE=${SWIFT_LOOPBACK_DISK_SIZE:-1000000}

 # By default we define 9 for the partition count (which mean 512).

 SWIFT_PARTITION_POWER_SIZE=${SWIFT_PARTITION_POWER_SIZE:-9}

-# This variable allows you to configure how many replicas you want to be

+# Set ``SWIFT_REPLICAS`` to configure how many replicas are to be

 # configured for your Swift cluster.  By default the three replicas would need a

 # bit of IO and Memory on a VM you may want to lower that to 1 if you want to do

 # only some quick testing.

@@ -514,8 +530,8 @@ S3_SERVICE_PORT=${S3_SERVICE_PORT:-3333}

 # Keystone

 # --------

-# Service Token - Openstack components need to have an admin token

-# to validate user tokens.

+# The ``SERVICE_TOKEN`` is used to bootstrap the Keystone database.  It is

+# just a string and is not a 'real' Keystone token.

 read_password SERVICE_TOKEN "ENTER A SERVICE_TOKEN TO USE FOR THE SERVICE ADMIN TOKEN."

 # Services authenticate to Identity with servicename/SERVICE_PASSWORD

 read_password SERVICE_PASSWORD "ENTER A SERVICE_PASSWORD TO USE FOR THE SERVICE AUTHENTICATION."

@@ -547,10 +563,10 @@ APACHE_GROUP=${APACHE_GROUP:-$APACHE_USER}

 # Log files

 # ---------

-# Set up logging for stack.sh

-# Set LOGFILE to turn on logging

-# We append '.xxxxxxxx' to the given name to maintain history

-# where xxxxxxxx is a representation of the date the file was created

+# Set up logging for ``stack.sh``

+# Set ``LOGFILE`` to turn on logging

+# Append '.xxxxxxxx' to the given name to maintain history

+# where 'xxxxxxxx' is a representation of the date the file was created

 if [[ -n "$LOGFILE" || -n "$SCREEN_LOGDIR" ]]; then

     LOGDAYS=${LOGDAYS:-7}

     TIMESTAMP_FORMAT=${TIMESTAMP_FORMAT:-"%F-%H%M%S"}

@@ -558,7 +574,7 @@ if [[ -n "$LOGFILE" || -n "$SCREEN_LOGDIR" ]]; then

 fi

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

-    # First clean up old log files.  Use the user-specified LOGFILE

+    # First clean up old log files.  Use the user-specified ``LOGFILE``

     # as the template to search for, appending '.*' to match the date

     # we added on earlier runs.

     LOGDIR=$(dirname "$LOGFILE")

@@ -575,11 +591,11 @@ if [[ -n "$LOGFILE" ]]; then

 fi

 # Set up logging of screen windows

-# Set SCREEN_LOGDIR to turn on logging of screen windows to the

-# directory specified in SCREEN_LOGDIR, we will log to the the file

-# screen-$SERVICE_NAME-$TIMESTAMP.log in that dir and have a link

-# screen-$SERVICE_NAME.log to the latest log file.

-# Logs are kept for as long specified in LOGDAYS.

+# Set ``SCREEN_LOGDIR`` to turn on logging of screen windows to the

+# directory specified in ``SCREEN_LOGDIR``, we will log to the the file

+# ``screen-$SERVICE_NAME-$TIMESTAMP.log`` in that dir and have a link

+# ``screen-$SERVICE_NAME.log`` to the latest log file.

+# Logs are kept for as long specified in ``LOGDAYS``.

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

     # We make sure the directory is created.

@@ -591,8 +607,11 @@ if [[ -n "$SCREEN_LOGDIR" ]]; then

     fi

 fi

-# So that errors don't compound we exit on any errors so you see only the

-# first error that occurred.

+

+# Set Up Script Execution

+# -----------------------

+

+# Exit on any errors so that errors don't compound

 trap failed ERR

 failed() {

     local r=$?

@@ -609,7 +628,7 @@ set -o xtrace

 # Install Packages

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

-# Openstack uses a fair number of other projects.

+# OpenStack uses a fair number of other projects.

 # Install package requirements

 if [[ "$os_PACKAGE" = "deb" ]]; then

@@ -650,7 +669,7 @@ mysql-server-5.1 mysql-server/start_on_boot boolean true

 MYSQL_PRESEED

     fi

-    # while ``.my.cnf`` is not needed for openstack to function, it is useful

+    # while ``.my.cnf`` is not needed for OpenStack to function, it is useful

     # as it allows you to access the mysql databases via ``mysql nova`` instead

     # of having to specify the username/password each time.

     if [[ ! -e $HOME/.my.cnf ]]; then

@@ -702,8 +721,6 @@ fi

 if is_service_enabled n-cpu; then

-    # Virtualization Configuration

-    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

     if [[ "$os_PACKAGE" = "deb" ]]; then

         LIBVIRT_PKG_NAME=libvirt-bin

     else

@@ -746,7 +763,10 @@ fi

 # Install python requirements

 pip_install $(get_packages $FILES/pips | sort -u)

-# Check out OpenStack sources

+

+# Check Out Source

+# ----------------

+

 git_clone $NOVA_REPO $NOVA_DIR $NOVA_BRANCH

 # Check out the client libs that are used most

@@ -799,6 +819,7 @@ if is_service_enabled ceilometer; then

     install_ceilometer

 fi

+

 # Initialization

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

@@ -822,6 +843,7 @@ if is_service_enabled g-api n-api; then

 fi

 # Do this _after_ glance is installed to override the old binary

+# TODO(dtroyer): figure out when this is no longer necessary

 setup_develop $GLANCECLIENT_DIR

 setup_develop $NOVA_DIR

@@ -848,6 +870,7 @@ if [[ $TRACK_DEPENDS = True ]] ; then

     exit 0

 fi

+

 # Syslog

 # ------

@@ -889,10 +912,9 @@ fi

 # Mysql

 # -----

-

 if is_service_enabled mysql; then

-    #start mysql-server

+    # Start mysql-server

     if [[ "$os_PACKAGE" = "rpm" ]]; then

         # RPM doesn't start the service

         start_service mysqld

@@ -1015,7 +1037,8 @@ if is_service_enabled horizon; then

         APACHE_CONF=conf.d/horizon.conf

         sudo sed '/^Listen/s/^.*$/Listen 0.0.0.0:80/' -i /etc/httpd/conf/httpd.conf

     fi

-    ## Configure apache to run horizon

+

+    # Configure apache to run horizon

     sudo sh -c "sed -e \"

         s,%USER%,$APACHE_USER,g;

         s,%GROUP%,$APACHE_GROUP,g;

@@ -1023,6 +1046,7 @@ if is_service_enabled horizon; then

         s,%APACHE_NAME%,$APACHE_NAME,g;

         s,%DEST%,$DEST,g;

     \" $FILES/apache-horizon.template >/etc/$APACHE_NAME/$APACHE_CONF"

+

     restart_service $APACHE_NAME

 fi

@@ -1106,7 +1130,7 @@ fi

 # -------

 if is_service_enabled quantum; then

-    # Put config files in /etc/quantum for everyone to find

+    # Put config files in ``/etc/quantum`` for everyone to find

     if [[ ! -d /etc/quantum ]]; then

         sudo mkdir -p /etc/quantum

     fi

@@ -1127,7 +1151,7 @@ if is_service_enabled quantum; then

         exit 1

     fi

-    # If needed, move config file from $QUANTUM_DIR/etc/quantum to /etc/quantum

+    # If needed, move config file from ``$QUANTUM_DIR/etc/quantum`` to ``/etc/quantum``

     mkdir -p /$Q_PLUGIN_CONF_PATH

     Q_PLUGIN_CONF_FILE=$Q_PLUGIN_CONF_PATH/$Q_PLUGIN_CONF_FILENAME

     cp $QUANTUM_DIR/$Q_PLUGIN_CONF_FILE /$Q_PLUGIN_CONF_FILE

@@ -1265,10 +1289,11 @@ screen_it q-agt "sudo python $AGENT_BINARY --config-file $Q_CONF_FILE --config-f

 # Start up the quantum agent

 screen_it q-dhcp "sudo python $AGENT_DHCP_BINARY --config-file $Q_CONF_FILE --config-file=$Q_DHCP_CONF_FILE"

+

 # Nova

 # ----

-# Put config files in /etc/nova for everyone to find

+# Put config files in ``/etc/nova`` for everyone to find

 NOVA_CONF_DIR=/etc/nova

 if [[ ! -d $NOVA_CONF_DIR ]]; then

     sudo mkdir -p $NOVA_CONF_DIR

@@ -1278,7 +1303,7 @@ sudo chown `whoami` $NOVA_CONF_DIR

 cp -p $NOVA_DIR/etc/nova/policy.json $NOVA_CONF_DIR

 # If Nova ships the new rootwrap filters files, deploy them

-# (owned by root) and add a parameter to $NOVA_ROOTWRAP

+# (owned by root) and add a parameter to ``$NOVA_ROOTWRAP``

 ROOTWRAP_SUDOER_CMD="$NOVA_ROOTWRAP"

 if [[ -d $NOVA_DIR/etc/nova/rootwrap.d ]]; then

     # Wipe any existing rootwrap.d files first

@@ -1351,7 +1376,7 @@ if is_service_enabled n-cpu; then

     # Force IP forwarding on, just on case

     sudo sysctl -w net.ipv4.ip_forward=1

-    # attempt to load modules: network block device - used to manage qcow images

+    # Attempt to load modules: network block device - used to manage qcow images

     sudo modprobe nbd || true

     # Check for kvm (hardware based virtualization).  If unable to initialize

@@ -1415,9 +1440,11 @@ ResultActive=yes

 EOF'

         LIBVIRT_DAEMON=libvirtd

     fi

-    # The user that nova runs as needs to be member of libvirtd group otherwise

+

+    # The user that nova runs as needs to be member of **libvirtd** group otherwise

     # nova-compute will be unable to use libvirt.

     sudo usermod -a -G libvirtd `whoami`

+

     # libvirt detects various settings on startup, as we potentially changed

     # the system configuration (modules, filesystems), we need to restart

     # libvirt to detect those changes.

@@ -1475,17 +1502,17 @@ fi

 if is_service_enabled swift; then

-    # We make sure to kill all swift processes first

+    # Make sure to kill all swift processes first

     swift-init all stop || true

-    # We first do a bit of setup by creating the directories and

+    # First do a bit of setup by creating the directories and

     # changing the permissions so we can run it as our user.

     USER_GROUP=$(id -g)

     sudo mkdir -p ${SWIFT_DATA_DIR}/drives

     sudo chown -R $USER:${USER_GROUP} ${SWIFT_DATA_DIR}

-    # We then create a loopback disk and format it to XFS.

+    # Create a loopback disk and format it to XFS.

     if [[ -e ${SWIFT_DATA_DIR}/drives/images/swift.img ]]; then

         if egrep -q ${SWIFT_DATA_DIR}/drives/sdb1 /proc/mounts; then

             sudo umount ${SWIFT_DATA_DIR}/drives/sdb1

@@ -1498,24 +1525,22 @@ if is_service_enabled swift; then

         dd if=/dev/zero of=${SWIFT_DATA_DIR}/drives/images/swift.img \

             bs=1024 count=0 seek=${SWIFT_LOOPBACK_DISK_SIZE}

     fi

+

     # Make a fresh XFS filesystem

     mkfs.xfs -f -i size=1024  ${SWIFT_DATA_DIR}/drives/images/swift.img

-    # After the drive being created we mount the disk with a few mount

-    # options to make it most efficient as possible for swift.

+    # Mount the disk with mount options to make it as efficient as possible

     mkdir -p ${SWIFT_DATA_DIR}/drives/sdb1

     if ! egrep -q ${SWIFT_DATA_DIR}/drives/sdb1 /proc/mounts; then

         sudo mount -t xfs -o loop,noatime,nodiratime,nobarrier,logbufs=8  \

             ${SWIFT_DATA_DIR}/drives/images/swift.img ${SWIFT_DATA_DIR}/drives/sdb1

     fi

-    # We then create link to that mounted location so swift would know

-    # where to go.

+    # Create a link to the above mount

     for x in $(seq ${SWIFT_REPLICAS}); do

         sudo ln -sf ${SWIFT_DATA_DIR}/drives/sdb1/$x ${SWIFT_DATA_DIR}/$x; done

-    # We now have to emulate a few different servers into one we

-    # create all the directories needed for swift

+    # Create all of the directories needed to emulate a few different servers

     for x in $(seq ${SWIFT_REPLICAS}); do

             drive=${SWIFT_DATA_DIR}/drives/sdb1/${x}

             node=${SWIFT_DATA_DIR}/${x}/node

@@ -1531,7 +1556,7 @@ if is_service_enabled swift; then

    sudo chown -R $USER: ${SWIFT_CONFIG_DIR} /var/run/swift

     if [[ "$SWIFT_CONFIG_DIR" != "/etc/swift" ]]; then

-        # Some swift tools are hard-coded to use /etc/swift and are apparenty not going to be fixed.

+        # Some swift tools are hard-coded to use ``/etc/swift`` and are apparenty not going to be fixed.

         # Create a symlink if the config dir is moved

         sudo ln -sf ${SWIFT_CONFIG_DIR} /etc/swift

     fi

@@ -1622,9 +1647,8 @@ EOF

     cp ${SWIFT_DIR}/etc/swift.conf-sample ${SWIFT_CONFIG_DIR}/swift.conf

     iniset ${SWIFT_CONFIG_DIR}/swift.conf swift-hash swift_hash_path_suffix ${SWIFT_HASH}

-    # We need to generate a object/account/proxy configuration

-    # emulating 4 nodes on different ports we have a little function

-    # that help us doing that.

+    # This function generates an object/account/proxy configuration

+    # emulating 4 nodes on different ports

     function generate_swift_configuration() {

         local server_type=$1

         local bind_port=$2

@@ -1667,8 +1691,8 @@ EOF

     generate_swift_configuration container 6011 2

     generate_swift_configuration account 6012 2

-    # We have some specific configuration for swift for rsyslog. See

-    # the file /etc/rsyslog.d/10-swift.conf for more info.

+    # Specific configuration for swift for rsyslog. See