Mostly docs cleanups
Fix documentation build errors and RST formatting
Change-Id: Id93153400c5b069dd9d772381558c7085f64c207
diff --git a/tools/build_docs.sh b/tools/build_docs.sh
index 2aa0a0a..fda86c0 100755
--- a/tools/build_docs.sh
+++ b/tools/build_docs.sh
@@ -2,8 +2,8 @@
# **build_docs.sh** - Build the docs for DevStack
#
-# - Install shocco if not found on PATH and INSTALL_SHOCCO is set
-# - Clone MASTER_REPO branch MASTER_BRANCH
+# - Install shocco if not found on ``PATH`` and ``INSTALL_SHOCCO`` is set
+# - Clone ``MASTER_REPO`` branch ``MASTER_BRANCH``
# - Re-creates ``doc/build/html`` directory from existing repo + new generated script docs
# Usage:
@@ -16,7 +16,7 @@
HTML_BUILD=doc/build/html
-# Keep track of the devstack directory
+# Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
# Uses this shocco branch: https://github.com/dtroyer/shocco/tree/rst_support
diff --git a/tools/build_venv.sh b/tools/build_venv.sh
index 11d1d35..cfa39a8 100755
--- a/tools/build_venv.sh
+++ b/tools/build_venv.sh
@@ -4,11 +4,12 @@
#
# build_venv.sh venv-path [package [...]]
#
+# Installs basic common prereq packages that require compilation
+# to allow quick copying of resulting venv as a baseline
+#
# Assumes:
# - a useful pip is installed
# - virtualenv will be installed by pip
-# - installs basic common prereq packages that require compilation
-# to allow quick copying of resulting venv as a baseline
VENV_DEST=${1:-.venv}
@@ -16,14 +17,14 @@
MORE_PACKAGES="$@"
-# If TOP_DIR is set we're being sourced rather than running stand-alone
+# If ``TOP_DIR`` is set we're being sourced rather than running stand-alone
# or in a sub-shell
if [[ -z "$TOP_DIR" ]]; then
set -o errexit
set -o nounset
- # Keep track of the devstack directory
+ # Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
FILES=$TOP_DIR/files
diff --git a/tools/build_wheels.sh b/tools/build_wheels.sh
index f1740df..c57568f 100755
--- a/tools/build_wheels.sh
+++ b/tools/build_wheels.sh
@@ -4,21 +4,22 @@
#
# build_wheels.sh [package [...]]
#
-# System package prerequisites listed in files/*/devlibs will be installed
+# System package prerequisites listed in ``files/*/devlibs`` will be installed
#
# Builds wheels for all virtual env requirements listed in
# ``venv-requirements.txt`` plus any supplied on the command line.
#
-# Assumes ``tools/install_pip.sh`` has been run and a suitable pip/setuptools is available.
+# Assumes:
+# - ``tools/install_pip.sh`` has been run and a suitable ``pip/setuptools`` is available.
-# If TOP_DIR is set we're being sourced rather than running stand-alone
+# If ``TOP_DIR`` is set we're being sourced rather than running stand-alone
# or in a sub-shell
if [[ -z "$TOP_DIR" ]]; then
set -o errexit
set -o nounset
- # Keep track of the devstack directory
+ # Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
FILES=$TOP_DIR/files
@@ -59,7 +60,7 @@
# Install modern pip and wheel
PIP_VIRTUAL_ENV=$TMP_VENV_PATH pip_install -U pip wheel
-# VENV_PACKAGES is a list of packages we want to pre-install
+# ``VENV_PACKAGES`` is a list of packages we want to pre-install
VENV_PACKAGE_FILE=$FILES/venv-requirements.txt
if [[ -r $VENV_PACKAGE_FILE ]]; then
VENV_PACKAGES=$(grep -v '^#' $VENV_PACKAGE_FILE)
diff --git a/tools/create-stack-user.sh b/tools/create-stack-user.sh
index 9c29ecd..b49164b 100755
--- a/tools/create-stack-user.sh
+++ b/tools/create-stack-user.sh
@@ -17,7 +17,7 @@
set -o errexit
-# Keep track of the devstack directory
+# Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
# Import common functions
diff --git a/tools/fixup_stuff.sh b/tools/fixup_stuff.sh
index f8edd16..2efb4e0 100755
--- a/tools/fixup_stuff.sh
+++ b/tools/fixup_stuff.sh
@@ -17,7 +17,7 @@
# - uninstall firewalld (f20 only)
-# If TOP_DIR is set we're being sourced rather than running stand-alone
+# If ``TOP_DIR`` is set we're being sourced rather than running stand-alone
# or in a sub-shell
if [[ -z "$TOP_DIR" ]]; then
set -o errexit
@@ -27,7 +27,7 @@
TOOLS_DIR=$(cd $(dirname "$0") && pwd)
TOP_DIR=$(cd $TOOLS_DIR/..; pwd)
- # Change dir to top of devstack
+ # Change dir to top of DevStack
cd $TOP_DIR
# Import common functions
@@ -38,7 +38,7 @@
# Keystone Port Reservation
# -------------------------
-# Reserve and prevent $KEYSTONE_AUTH_PORT and $KEYSTONE_AUTH_PORT_INT from
+# Reserve and prevent ``KEYSTONE_AUTH_PORT`` and ``KEYSTONE_AUTH_PORT_INT`` from
# being used as ephemeral ports by the system. The default(s) are 35357 and
# 35358 which are in the Linux defined ephemeral port range (in disagreement
# with the IANA ephemeral port range). This is a workaround for bug #1253482
@@ -47,9 +47,9 @@
# exception into the Kernel for the Keystone AUTH ports.
keystone_ports=${KEYSTONE_AUTH_PORT:-35357},${KEYSTONE_AUTH_PORT_INT:-35358}
-# only do the reserved ports when available, on some system (like containers)
+# Only do the reserved ports when available, on some system (like containers)
# where it's not exposed we are almost pretty sure these ports would be
-# exclusive for our devstack.
+# exclusive for our DevStack.
if sysctl net.ipv4.ip_local_reserved_ports >/dev/null 2>&1; then
# Get any currently reserved ports, strip off leading whitespace
reserved_ports=$(sysctl net.ipv4.ip_local_reserved_ports | awk -F'=' '{print $2;}' | sed 's/^ //')
@@ -59,7 +59,7 @@
sudo sysctl -w net.ipv4.ip_local_reserved_ports=${keystone_ports}
else
# If there are currently reserved ports, keep those and also reserve the
- # keystone specific ports. Duplicate reservations are merged into a single
+ # Keystone specific ports. Duplicate reservations are merged into a single
# reservation (or range) automatically by the kernel.
sudo sysctl -w net.ipv4.ip_local_reserved_ports=${keystone_ports},${reserved_ports}
fi
diff --git a/tools/image_list.sh b/tools/image_list.sh
index 88c1d09..2042807 100755
--- a/tools/image_list.sh
+++ b/tools/image_list.sh
@@ -1,6 +1,6 @@
#!/bin/bash
-# Keep track of the devstack directory
+# Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
source $TOP_DIR/functions
diff --git a/tools/info.sh b/tools/info.sh
index a8f9544..433206e 100755
--- a/tools/info.sh
+++ b/tools/info.sh
@@ -2,7 +2,7 @@
# **info.sh**
-# Produce a report on the state of devstack installs
+# Produce a report on the state of DevStack installs
#
# Output fields are separated with '|' chars
# Output types are git,localrc,os,pip,pkg:
@@ -14,7 +14,7 @@
# pkg|<package>|<version>
function usage {
- echo "$0 - Report on the devstack configuration"
+ echo "$0 - Report on the DevStack configuration"
echo ""
echo "Usage: $0"
exit 1
diff --git a/tools/install_pip.sh b/tools/install_pip.sh
index b7b40c7..0f7c962 100755
--- a/tools/install_pip.sh
+++ b/tools/install_pip.sh
@@ -16,7 +16,7 @@
TOOLS_DIR=$(cd $(dirname "$0") && pwd)
TOP_DIR=`cd $TOOLS_DIR/..; pwd`
-# Change dir to top of devstack
+# Change dir to top of DevStack
cd $TOP_DIR
# Import common functions
@@ -42,11 +42,11 @@
function install_get_pip {
- # the openstack gate and others put a cached version of get-pip.py
+ # The OpenStack gate and others put a cached version of get-pip.py
# for this to find, explicitly to avoid download issues.
#
- # However, if devstack *did* download the file, we want to check
- # for updates; people can leave thier stacks around for a long
+ # However, if DevStack *did* download the file, we want to check
+ # for updates; people can leave their stacks around for a long
# time and in the mean-time pip might get upgraded.
#
# Thus we use curl's "-z" feature to always check the modified
@@ -74,7 +74,7 @@
touch $PIP_CONFIG_FILE
fi
if ! ini_has_option "$PIP_CONFIG_FILE" "global" "index-url"; then
- #it means that the index-url does not exist
+ # It means that the index-url does not exist
iniset "$PIP_CONFIG_FILE" "global" "index-url" "$PYPI_OVERRIDE"
fi
diff --git a/tools/install_prereqs.sh b/tools/install_prereqs.sh
index 917980c..a07e58d 100755
--- a/tools/install_prereqs.sh
+++ b/tools/install_prereqs.sh
@@ -18,10 +18,10 @@
esac
done
-# If TOP_DIR is set we're being sourced rather than running stand-alone
+# If ``TOP_DIR`` is set we're being sourced rather than running stand-alone
# or in a sub-shell
if [[ -z "$TOP_DIR" ]]; then
- # Keep track of the devstack directory
+ # Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
# Import common functions
@@ -65,7 +65,7 @@
PACKAGES="$PACKAGES $(get_plugin_packages)"
if is_ubuntu && echo $PACKAGES | grep -q dkms ; then
- # ensure headers for the running kernel are installed for any DKMS builds
+ # Ensure headers for the running kernel are installed for any DKMS builds
PACKAGES="$PACKAGES linux-headers-$(uname -r)"
fi
diff --git a/tools/ironic/scripts/create-node b/tools/ironic/scripts/create-node
index 25b53d4..b018acd 100755
--- a/tools/ironic/scripts/create-node
+++ b/tools/ironic/scripts/create-node
@@ -6,13 +6,13 @@
set -ex
-# Keep track of the devstack directory
+# Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
NAME=$1
CPU=$2
MEM=$(( 1024 * $3 ))
-# extra G to allow fuzz for partition table : flavor size and registered size
+# Extra G to allow fuzz for partition table : flavor size and registered size
# need to be different to actual size.
DISK=$(( $4 + 1))
diff --git a/tools/ironic/scripts/setup-network b/tools/ironic/scripts/setup-network
index e326bf8..83308ed 100755
--- a/tools/ironic/scripts/setup-network
+++ b/tools/ironic/scripts/setup-network
@@ -9,7 +9,7 @@
LIBVIRT_CONNECT_URI=${LIBVIRT_CONNECT_URI:-"qemu:///system"}
-# Keep track of the devstack directory
+# Keep track of the DevStack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
BRIDGE_SUFFIX=${1:-''}
BRIDGE_NAME=brbm$BRIDGE_SUFFIX
@@ -19,7 +19,7 @@
# Only add bridge if missing
(sudo ovs-vsctl list-br | grep ${BRIDGE_NAME}$) || sudo ovs-vsctl add-br ${BRIDGE_NAME}
-# remove bridge before replacing it.
+# Remove bridge before replacing it.
(virsh net-list | grep "${BRIDGE_NAME} ") && virsh net-destroy ${BRIDGE_NAME}
(virsh net-list --inactive | grep "${BRIDGE_NAME} ") && virsh net-undefine ${BRIDGE_NAME}
diff --git a/tools/outfilter.py b/tools/outfilter.py
index 9686a38..f82939b 100755
--- a/tools/outfilter.py
+++ b/tools/outfilter.py
@@ -14,8 +14,8 @@
# License for the specific language governing permissions and limitations
# under the License.
-# This is an output filter to filter and timestamp the logs from grenade and
-# devstack. Largely our awk filters got beyond the complexity level which were
+# This is an output filter to filter and timestamp the logs from Grenade and
+# DevStack. Largely our awk filters got beyond the complexity level which were
# sustainable, so this provides us much more control in a single place.
#
# The overhead of running python should be less than execing `date` a million
@@ -32,7 +32,7 @@
def get_options():
parser = argparse.ArgumentParser(
- description='Filter output by devstack and friends')
+ description='Filter output by DevStack and friends')
parser.add_argument('-o', '--outfile',
help='Output file for content',
default=None)
@@ -52,7 +52,7 @@
if opts.outfile:
outfile = open(opts.outfile, 'a', 0)
- # otherwise fileinput reprocess args as files
+ # Otherwise fileinput reprocess args as files
sys.argv = []
while True:
line = sys.stdin.readline()
@@ -63,9 +63,9 @@
if skip_line(line):
continue
- # this prevents us from nesting date lines, because
- # we'd like to pull this in directly in grenade and not double
- # up on devstack lines
+ # This prevents us from nesting date lines, because
+ # we'd like to pull this in directly in Grenade and not double
+ # up on DevStack lines
if HAS_DATE.search(line) is None:
now = datetime.datetime.utcnow()
line = ("%s | %s" % (