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

 # **swift.sh**

-# Test swift via the ``swift`` command line from ``python-swiftclient`

+# Test swift via the ``swift`` command line from ``python-swiftclient``

 echo "*********************************************************************"

 echo "Begin DevStack Exercise: $0"

@@ -54,7 +54,7 @@ function address_in_net() {

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

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

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

 # apt_get operation package [package ...]

 function apt_get() {

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

@@ -260,7 +260,8 @@ function _get_package_dir() {

 #

 # Only packages required for the services in 1st argument will be

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

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

+#

+# - ``# 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.

 function get_packages() {

@@ -982,7 +983,7 @@ function is_set() {

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

 # Uses globals ``OFFLINE``, ``PIP_DOWNLOAD_CACHE``, ``PIP_USE_MIRRORS``,

-#   ``TRACK_DEPENDS``, ``*_proxy`

+# ``TRACK_DEPENDS``, ``*_proxy``

 # pip_install package [package ...]

 function pip_install {

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

@@ -1011,8 +1012,7 @@ function pip_install {

     # /tmp/$USER-pip-build.  Even if a later component specifies foo <

     # 1.1, the existing extracted build will be used and cause

     # confusing errors.  By creating unique build directories we avoid

-    # this problem. See

-    #  https://github.com/pypa/pip/issues/709

+    # this problem. See https://github.com/pypa/pip/issues/709

     local pip_build_tmp=$(mktemp --tmpdir -d pip-build.XXXXX)

     $SUDO_PIP PIP_DOWNLOAD_CACHE=${PIP_DOWNLOAD_CACHE:-/var/cache/pip} \

@@ -1146,8 +1146,8 @@ function screen_rc {

 }

-# Helper to remove the *.failure files under $SERVICE_DIR/$SCREEN_NAME

-# This is used for service_check when all the screen_it are called finished

+# Helper to remove the ``*.failure`` files under ``$SERVICE_DIR/$SCREEN_NAME``.

+# This is used for ``service_check`` when all the ``screen_it`` are called finished

 # init_service_check

 function init_service_check() {

     SCREEN_NAME=${SCREEN_NAME:-stack}

@@ -1301,10 +1301,12 @@ function trueorfalse() {

 }

-# Retrieve an image from a URL and upload into Glance

+# 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

@@ -1466,7 +1468,8 @@ function upload_image() {

 # When called from stackrc/localrc DATABASE_BACKENDS has not been

 # initialized yet, just save the configuration selection and call back later

 # to validate it.

-#  $1 The name of the database backend to use (mysql, postgresql, ...)

+#

+# ``$1`` - the name of the database backend to use (mysql, postgresql, ...)

 function use_database {

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

         # No backends registered means this is likely called from ``localrc``

@@ -1507,7 +1510,7 @@ function wait_for_service() {

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

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

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

 # yum_install package [package ...]

 function yum_install() {

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

@@ -83,8 +83,10 @@ BM_POSEUR_EXTRA_OPTS=${BM_POSEUR_EXTRA_OPTS:-}

 # To provide PXE, configure nova-network's dnsmasq rather than run the one

 # dedicated to baremetal. When enable this, make sure these conditions are

 # fulfilled:

+#

 #  1) nova-compute and nova-network runs on the same host

 #  2) nova-network uses FlatDHCPManager

+#

 # NOTE: the other BM_DNSMASQ_* have no effect on the behavior if this option

 #       is enabled.

 BM_DNSMASQ_FROM_NOVA_NETWORK=`trueorfalse False $BM_DNSMASQ_FROM_NOVA_NETWORK`

@@ -198,8 +200,8 @@ function create_fake_baremetal_env() {

     BM_FIRST_MAC=$(sudo $bm_poseur get-macs)

     # NOTE: there is currently a limitation in baremetal driver

-    #       that requires second MAC even if it is not used.

-    #       Passing a fake value allows this to work.

+    # that requires second MAC even if it is not used.

+    # Passing a fake value allows this to work.

     # TODO(deva): remove this after driver issue is fixed.

     BM_SECOND_MAC='12:34:56:78:90:12'

 }

@@ -2,9 +2,11 @@

 # Install and start **Ceilometer** service

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

+#

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

 #

 # To ensure Ceilometer alarming services are enabled also, further add to the localrc:

+#

 #   enable_service ceilometer-alarm-notifier ceilometer-alarm-evaluator

 # Dependencies:

@@ -9,10 +9,11 @@

 # This is a wrapper for the specific database backends available.

 # Each database must implement four functions:

-#   recreate_database_$DATABASE_TYPE

-#   install_database_$DATABASE_TYPE

-#   configure_database_$DATABASE_TYPE

-#   database_connection_url_$DATABASE_TYPE

+#

+# - recreate_database_$DATABASE_TYPE

+# - install_database_$DATABASE_TYPE

+# - configure_database_$DATABASE_TYPE

+# - database_connection_url_$DATABASE_TYPE

 #

 # and call register_database $DATABASE_TYPE

@@ -22,7 +23,9 @@ set +o xtrace

 # Register a database backend

-#  $1 The name of the database backend

+#

+#   $1 The name of the database backend

+#

 # This is required to be defined before the specific database scripts are sourced

 function register_database {

     [ -z "$DATABASE_BACKENDS" ] && DATABASE_BACKENDS=$1 || DATABASE_BACKENDS+=" $1"

@@ -208,7 +208,7 @@ source $TOP_DIR/lib/neutron_plugins/services/loadbalancer

 source $TOP_DIR/lib/neutron_plugins/services/vpn

 # Firewall Service Plugin functions

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

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

 source $TOP_DIR/lib/neutron_plugins/services/firewall

 # Use security group or not

@@ -494,6 +494,7 @@ function _configure_neutron_common() {

     # For main plugin config file, set ``Q_PLUGIN_CONF_PATH``, ``Q_PLUGIN_CONF_FILENAME``.

     # For addition plugin config files, set ``Q_PLUGIN_EXTRA_CONF_PATH``,

     # ``Q_PLUGIN_EXTRA_CONF_FILES``.  For example:

+    #

     #    ``Q_PLUGIN_EXTRA_CONF_FILES=(file1, file2)``

     neutron_plugin_configure_common

@@ -268,8 +268,8 @@ function configure_swift() {

     # 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_

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

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

     if is_service_enabled swift3;then

         swift_pipeline=" swift3 s3token "

     fi

@@ -84,11 +84,10 @@ if [ ! -r $CACHEDIR/$DIST_NAME-base.img ]; then

     $TOOLS_DIR/get_uec_image.sh $DIST_NAME $CACHEDIR/$DIST_NAME-base.img

 fi

-# Finds the next available NBD device

-# Exits script if error connecting or none free

+# Finds and returns full device path for the next available NBD device.

+# Exits script if error connecting or none free.

 # map_nbd image

-# Returns full nbd device path

-function map_nbd {

+function map_nbd() {

     for i in `seq 0 15`; do

         if [ ! -e /sys/block/nbd$i/pid ]; then

             NBD=/dev/nbd$i

@@ -156,7 +155,7 @@ if [ ! -r $IMG_FILE ]; then

     # Pre-create the image file

     # FIXME(dt): This should really get the partition size to

-    #            pre-create the image file

+    # pre-create the image file

     dd if=/dev/zero of=$IMG_FILE_TMP bs=1 count=1 seek=$((2*1024*1024*1024))

     # Create filesystem image for RAM disk

     dd if=${NBD}p1 of=$IMG_FILE_TMP bs=1M

@@ -5,7 +5,9 @@

 # Create a user account suitable for running DevStack

 # - create a group named $STACK_USER if it does not exist

 # - create a user named $STACK_USER if it does not exist

+#

 #   - home is $DEST

+#

 # - configure sudo for $STACK_USER

 # ``stack.sh`` was never intended to run as root.  It had a hack to do what is

@@ -5,11 +5,15 @@

 # fixup_stuff.sh

 #

 # All distro and package specific hacks go in here

+#

 # - prettytable 0.7.2 permissions are 600 in the package and

 #   pip 1.4 doesn't fix it (1.3 did)

+#

 # - httplib2 0.8 permissions are 600 in the package and

 #   pip 1.4 doesn't fix it (1.3 did)

+#

 # - RHEL6:

+#

 #   - set selinux not enforcing

 #   - (re)start messagebus daemon

 #   - remove distro packages python-crypto and python-lxml

@@ -90,7 +94,7 @@ if [[ $DISTRO =~ (rhel6) ]]; then

         # fresh system via Anaconda and the dependency chain

         # ``cas`` -> ``python-paramiko`` -> ``python-crypto``.

         # ``pip uninstall pycrypto`` will remove the packaged ``.egg-info``

-        #  file but leave most of the actual library files behind in

+        # file but leave most of the actual library files behind in

         # ``/usr/lib64/python2.6/Crypto``. Later ``pip install pycrypto``

         # will install over the packaged files resulting

         # in a useless mess of old, rpm-packaged files and pip-installed files.