From cb961597cc30f9d8ece17529f09a8291454827e3 Mon Sep 17 00:00:00 2001
From: Adam Spiers <aspiers@suse.com>
Date: Sat, 5 Oct 2013 12:11:07 +0100
Subject: [PATCH] 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 +-
functions | 27 +++++++++++++++------------
lib/baremetal | 6 ++++--
lib/ceilometer | 2 ++
lib/database | 13 ++++++++-----
lib/neutron | 3 ++-
lib/swift | 4 ++--
tools/build_ramdisk.sh | 9 ++++-----
tools/create-stack-user.sh | 2 ++
tools/fixup_stuff.sh | 6 +++++-
10 files changed, 45 insertions(+), 29 deletions(-)
diff --git a/exercises/swift.sh b/exercises/swift.sh
index b9f1b566bb..25ea6719c1 100755
--- a/exercises/swift.sh
+++ b/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"
diff --git a/functions b/functions
index af5a37da17..8d076b72e5 100644
--- a/functions
+++ b/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
diff --git a/lib/baremetal b/lib/baremetal
index 141c28d15f..5606230eac 100644
--- a/lib/baremetal
+++ b/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'
}
diff --git a/lib/ceilometer b/lib/ceilometer
index cd4c4d8656..a471d9c7e6 100644
--- a/lib/ceilometer
+++ b/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:
diff --git a/lib/database b/lib/database
index 3c1560964c..c3fd435eb2 100644
--- a/lib/database
+++ b/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"
diff --git a/lib/neutron b/lib/neutron
index 44fb9e1005..00852df05a 100644
--- a/lib/neutron
+++ b/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
diff --git a/lib/swift b/lib/swift
index 8726f1e7fc..3c3b8b1d38 100644
--- a/lib/swift
+++ b/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
diff --git a/tools/build_ramdisk.sh b/tools/build_ramdisk.sh
index 2c45568531..3d9f76f4a5 100755
--- a/tools/build_ramdisk.sh
+++ b/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
diff --git a/tools/create-stack-user.sh b/tools/create-stack-user.sh
index 2251d1e67c..50f6592a3a 100755
--- a/tools/create-stack-user.sh
+++ b/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
diff --git a/tools/fixup_stuff.sh b/tools/fixup_stuff.sh
index 9e65b7c21e..325a6d6be1 100755
--- a/tools/fixup_stuff.sh
+++ b/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.