Fix docs build errors

Fix shocco errors during docs generation

Closes-Bug: 1362691
Change-Id: I2b7fb008c89f0b4e7280b2d0a054320765e83e47

functions

@@ -71,10 +71,10 @@ function upload_image {
         fi
         image="$FILES/${image_fname}"
     else
-        # File based URL (RFC 1738): file://host/path
+        # File based URL (RFC 1738): ``file://host/path``
         # Remote files are not considered here.
-        # *nix: file:///home/user/path/file
-        # windows: file:///C:/Documents%20and%20Settings/user/path/file
+        # unix: ``file:///home/user/path/file``
+        # windows: ``file:///C:/Documents%20and%20Settings/user/path/file``
         image=$(echo $image_url | sed "s/^file:\/\///g")
         if [[ ! -f $image || "$(stat -c "%s" $image)" == "0" ]]; then
             echo "Not found: $image_url"
@@ -123,7 +123,7 @@ function upload_image {
         if [[ "$vmdk_create_type" = "monolithicSparse" ]]; then
             vmdk_disktype="sparse"
         elif [[ "$vmdk_create_type" = "monolithicFlat" || "$vmdk_create_type" = "vmfs" ]]; then
-            # Attempt to retrieve the *-flat.vmdk
+            # Attempt to retrieve the ``*-flat.vmdk``
             local flat_fname="$(head -25 $image | { grep -G 'RW\|RDONLY [0-9]+ FLAT\|VMFS' $image || true; })"
             flat_fname="${flat_fname#*\"}"
             flat_fname="${flat_fname%?}"

functions-common

@@ -31,6 +31,7 @@
 # - ``TRACK_DEPENDS``
 # - ``UNDO_REQUIREMENTS``
 # - ``http_proxy``, ``https_proxy``, ``no_proxy``
+#
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -1253,7 +1254,8 @@ function screen_service {
         # - the pid of the background process is saved in the usual place
         # - the server process is brought back to the foreground
         # - if the server process exits prematurely the fg command errors
-        #   and a message is written to stdout and the service failure file
+        # and a message is written to stdout and the service failure file
+        #
         # The pid saved can be used in stop_process() as a process group
         # id to kill off all child processes
         if [[ -n "$group" ]]; then

lib/cinder_backends/xiv

@@ -16,6 +16,7 @@
 #
 # Authors:
 #   Alon Marx <alonma@il.ibm.com>
+#
 
 # lib/cinder_plugins/xiv
 # Configure the xiv_ds8k driver for xiv testing
@@ -61,7 +62,7 @@ function configure_cinder_backend_xiv {
     fi
 
     # For reference:
-    # XIV_DS8K_BACKEND='IBM-XIV_'${SAN_IP}'_'${SAN_CLUSTERNAME}'_'${CONNECTION_TYPE}
+    # ``XIV_DS8K_BACKEND='IBM-XIV_'${SAN_IP}'_'${SAN_CLUSTERNAME}'_'${CONNECTION_TYPE}``
     iniset $CINDER_CONF DEFAULT xiv_ds8k_driver_version $XIV_DRIVER_VERSION
 
     iniset $CINDER_CONF $be_name san_ip $SAN_IP

lib/neutron

@@ -177,9 +177,10 @@ fi
 
 # Distributed Virtual Router (DVR) configuration
 # Can be:
-#     legacy   - No DVR functionality
-#     dvr_snat - Controller or single node DVR
-#     dvr      - Compute node in multi-node DVR
+# - ``legacy``   - No DVR functionality
+# - ``dvr_snat`` - Controller or single node DVR
+# - ``dvr``      - Compute node in multi-node DVR
+#
 Q_DVR_MODE=${Q_DVR_MODE:-legacy}
 if [[ "$Q_DVR_MODE" != "legacy" ]]; then
     Q_ML2_PLUGIN_MECHANISM_DRIVERS=openvswitch,linuxbridge,l2population

lib/neutron_plugins/oneconvergence

@@ -1,5 +1,6 @@
 # Neutron One Convergence plugin
-# ---------------------------
+# ------------------------------
+
 # Save trace setting
 OC_XTRACE=$(set +o | grep xtrace)
 set +o xtrace

lib/nova

@@ -677,7 +677,7 @@ function start_nova_compute {
 
     if [[ "$VIRT_DRIVER" = 'libvirt' ]]; then
         # The group **$LIBVIRT_GROUP** is added to the current user in this script.
-        # sg' will be used in run_process to execute nova-compute as a member of the
+        # ``sg`` is used in run_process to execute nova-compute as a member of the
         # **$LIBVIRT_GROUP** group.
         run_process n-cpu "$NOVA_BIN_DIR/nova-compute --config-file $compute_cell_conf" $LIBVIRT_GROUP
     elif [[ "$VIRT_DRIVER" = 'fake' ]]; then

lib/nova_plugins/functions-libvirt

@@ -10,7 +10,7 @@ LV_XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
 # Defaults
-# -------
+# --------
 
 # if we should turn on massive libvirt debugging
 DEBUG_LIBVIRT=$(trueorfalse False $DEBUG_LIBVIRT)

lib/opendaylight

@@ -3,9 +3,9 @@
 
 # Dependencies:
 #
-# - ``functions`` file
-# # ``DEST`` must be defined
-# # ``STACK_USER`` must be defined
+# ``functions`` file
+# ``DEST`` must be defined
+# ``STACK_USER`` must be defined
 
 # ``stack.sh`` calls the entry points in this order:
 #
@@ -55,7 +55,7 @@ ODL_URL=${ODL_URL:-https://nexus.opendaylight.org/content/repositories/opendayli
 
 # Default arguments for OpenDaylight. This is typically used to set
 # Java memory options.
-#   ODL_ARGS=Xmx1024m -XX:MaxPermSize=512m
+# ``ODL_ARGS=Xmx1024m -XX:MaxPermSize=512m``
 ODL_ARGS=${ODL_ARGS:-"-XX:MaxPermSize=384m"}
 
 # How long to pause after ODL starts to let it complete booting
@@ -64,8 +64,6 @@ ODL_BOOT_WAIT=${ODL_BOOT_WAIT:-60}
 # The physical provider network to device mapping
 ODL_PROVIDER_MAPPINGS=${ODL_PROVIDER_MAPPINGS:-physnet1:eth1}
 
-# Set up default directories
-
 
 # Entry Points
 # ------------
@@ -139,6 +137,7 @@ function start_opendaylight {
     # The flags to ODL have the following meaning:
     #   -of13: runs ODL using OpenFlow 1.3 protocol support.
     #   -virt ovsdb: Runs ODL in "virtualization" mode with OVSDB support
+
     # NOTE(chdent): Leaving this as screen_it instead of run_process until
     # the right thing for this service is determined.
     screen_it odl-server "cd $ODL_DIR/opendaylight && JAVA_HOME=$JHOME ./run.sh $ODL_ARGS -of13 -virt ovsdb"

lib/tls

@@ -383,7 +383,7 @@ function start_tls_proxy {
 
 
 # Cleanup Functions
-# ===============
+# =================
 
 
 # Stops all stud processes. This should be done only after all services

stackrc

@@ -117,7 +117,7 @@ GIT_TIMEOUT=${GIT_TIMEOUT:-0}
 # ------------
 
 # Base GIT Repo URL
-# Another option is http://review.openstack.org/p
+# Another option is https://git.openstack.org
 GIT_BASE=${GIT_BASE:-git://git.openstack.org}
 
 # metering service

tools/create_userrc.sh

@@ -238,7 +238,7 @@ function get_user_id {
 }
 
 if [ $MODE != "create" ]; then
-# looks like I can't ask for all tenant related to a specified user
+    # looks like I can't ask for all tenant related to a specified user
     openstack project list --long --quote none -f csv | grep ',True' | grep -v "${SKIP_TENANT}" | while IFS=, read tenant_id tenant_name desc enabled; do
         openstack user list --project $tenant_id --long --quote none -f csv | grep ',True' | while IFS=, read user_id user_name project email enabled; do
             if [ $MODE = one -a "$user_name" != "$USER_NAME" ]; then
@@ -246,8 +246,7 @@ if [ $MODE != "create" ]; then
             fi
 
             # Checks for a specific password defined for an user.
-            # Example for an username johndoe:
-            #                     JOHNDOE_PASSWORD=1234
+            # Example for an username johndoe: JOHNDOE_PASSWORD=1234
             eval SPECIFIC_UPASSWORD="\$${USER_NAME^^}_PASSWORD"
             if [ -n "$SPECIFIC_UPASSWORD" ]; then
                 USER_PASS=$SPECIFIC_UPASSWORD