Mostly docs cleanups

Fix documentation build errors and RST formatting

Change-Id: Id93153400c5b069dd9d772381558c7085f64c207
diff --git a/gate/updown.sh b/gate/updown.sh
index d2d7351..f46385c 100755
--- a/gate/updown.sh
+++ b/gate/updown.sh
@@ -4,7 +4,7 @@
 #
 # Note: this is expected to start running as jenkins
 
-# Step 1: give back sudoers permissions to devstack
+# Step 1: give back sudoers permissions to DevStack
 TEMPFILE=`mktemp`
 echo "stack ALL=(root) NOPASSWD:ALL" >$TEMPFILE
 chmod 0440 $TEMPFILE