Merge "Add the doc build tools"
diff --git a/tools/build_docs.sh b/tools/build_docs.sh
new file mode 100755
index 0000000..216e557
--- /dev/null
+++ b/tools/build_docs.sh
@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+
+# **build_docs.sh** - Build the gh-pages docs for DevStack
+#
+# - Install shocco if not found on PATH
+# - Clone MASTER_REPO branch MASTER_BRANCH
+# - Re-creates ``docs`` directory from existing repo + new generated script docs
+
+# Usage:
+## build_docs.sh [[-b branch] [-p] repo] | .
+## -b branch The DevStack branch to check out (default is master; ignored if
+## repo is not specified)
+## -p Push the resulting docs tree to the source repo; fatal error if
+## repo is not specified
+## repo The DevStack repository to clone (default is DevStack github repo)
+## If a repo is not supplied use the current directory
+## (assumed to be a DevStack checkout) as the source.
+## . Use the current repo and branch (do not use with -p to
+## prevent stray files in the workspace being added tot he docs)
+
+# Defaults
+# --------
+
+# Source repo/branch for DevStack
+MASTER_REPO=${MASTER_REPO:-https://github.com/openstack-dev/devstack.git}
+MASTER_BRANCH=${MASTER_BRANCH:-master}
+
+# http://devstack.org is a GitHub gh-pages site in the https://github.com/cloudbuilders/devtack.git repo
+GH_PAGES_REPO=git@github.com:cloudbuilders/devstack.git
+
+# Uses this shocco branch: https://github.com/dtroyer/shocco/tree/rst_support
+SHOCCO=${SHOCCO:-shocco}
+if ! which shocco; then
+ if [[ ! -x shocco/shocco ]]; then
+ if [[ -z "$INSTALL_SHOCCO" ]]; then
+ echo "shocco not found in \$PATH, please set environment variable SHOCCO"
+ exit 1
+ fi
+ echo "Installing local copy of shocco"
+ git clone -b rst_support https://github.com/dtroyer/shocco shocco
+ cd shocco
+ ./configure
+ make
+ cd ..
+ fi
+ SHOCCO=shocco/shocco
+fi
+
+# Process command-line args
+while getopts b:p c; do
+ case $c in
+ b) MASTER_BRANCH=$OPTARG
+ ;;
+ p) PUSH_REPO=1
+ ;;
+ esac
+done
+shift `expr $OPTIND - 1`
+
+# Sanity check the args
+if [[ "$1" == "." ]]; then
+ REPO=""
+ if [[ -n $PUSH_REPO ]]; then
+ echo "Push not allowed from an active workspace"
+ unset PUSH_REPO
+ fi
+else
+ if [[ -z "$1" ]]; then
+ REPO=$MASTER_REPO
+ else
+ REPO=$1
+ fi
+fi
+
+# Check out a specific DevStack branch
+if [[ -n $REPO ]]; then
+ # Make a workspace
+ TMP_ROOT=$(mktemp -d devstack-docs-XXXX)
+ echo "Building docs in $TMP_ROOT"
+ cd $TMP_ROOT
+
+ # Get the master branch
+ git clone $REPO devstack
+ cd devstack
+ git checkout $MASTER_BRANCH
+fi
+
+# Processing
+# ----------
+
+# Assumption is we are now in the DevStack repo workspace to be processed
+
+# Pull the latest docs branch from devstack.org repo
+rm -rf docs || true
+git clone -b gh-pages $GH_PAGES_REPO docs
+
+# Build list of scripts to process
+FILES=""
+for f in $(find . -name .git -prune -o \( -type f -name \*.sh -not -path \*shocco/\* -print \)); do
+ echo $f
+ FILES+="$f "
+ mkdir -p docs/`dirname $f`;
+ $SHOCCO $f > docs/$f.html
+done
+for f in $(find functions lib samples -type f -name \*); do
+ echo $f
+ FILES+="$f "
+ mkdir -p docs/`dirname $f`;
+ $SHOCCO $f > docs/$f.html
+done
+echo "$FILES" >docs-files
+
+# Switch to the gh_pages repo
+cd docs
+
+# Collect the new generated pages
+find . -name \*.html -print0 | xargs -0 git add
+
+# Push our changes back up to the docs branch
+if ! git diff-index HEAD --quiet; then
+ git commit -a -m "Update script docs"
+ if [[ -n $PUSH ]]; then
+ git push
+ fi
+fi
+
+# Clean up or report the temp workspace
+if [[ -n REPO && -n $PUSH_REPO ]]; then
+ rm -rf $TMP_ROOT
+else
+ if [[ -z "$TMP_ROOT" ]]; then
+ TMP_ROOT="$(pwd)"
+ fi
+ echo "Built docs in $TMP_ROOT"
+fi