Fix shocco errors and warnings

A few Markdown-oriented issues were causing Docutils errors to
leak into the end-user docs on http://devstack.org

Change-Id: I51fa9698afb1bfb48596478d83bd1fdcd84ac52e

exercises/swift.sh

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

functions

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

lib/baremetal

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

lib/ceilometer

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

lib/database

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

lib/neutron

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

lib/swift

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

tools/build_ramdisk.sh

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

tools/create-stack-user.sh

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

tools/fixup_stuff.sh

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