Move static docs into master branch
The hand-maintained static HTML docs for DevStack have been in a
GitHub gh-pages branch; move them into the master branch in
preparation for hosting them in openstack.org infrastructure.
By default tools/build_docs.sh now builds the static HTML output
into docs/html.
Change-Id: Ide5f7d980a294c7a9f8a3decaed0939f1c239934
diff --git a/tools/build_docs.sh b/tools/build_docs.sh
index 384b1fa..77c2f4e 100755
--- a/tools/build_docs.sh
+++ b/tools/build_docs.sh
@@ -2,21 +2,22 @@
# **build_docs.sh** - Build the gh-pages docs for DevStack
#
-# - Install shocco if not found on PATH
+# - Install shocco if not found on PATH and INSTALL_SHOCCO is set
# - Clone MASTER_REPO branch MASTER_BRANCH
-# - Re-creates ``docs`` directory from existing repo + new generated script docs
+# - Re-creates ``docs/html`` 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)
+## build_docs.sh [-o <out-dir>] [-g] [master|<repo> [<branch>]]
+## <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.
+## <branch> The DevStack branch to check out (default is master; ignored if
+## repo is not specified)
## . Use the current repo and branch (do not use with -p to
## prevent stray files in the workspace being added tot he docs)
+## -o <out-dir> Write the static HTML output to <out-dir>
+## (Note that <out-dir> will be deleted and re-created to ensure it is clean)
+## -g Update the old gh-pages repo (set PUSH=1 to actualy push up to RCB)
# Defaults
# --------
@@ -28,6 +29,9 @@
# 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
+DOCS_SOURCE=docs/source
+HTML_BUILD=docs/html
+
# Keep track of the devstack directory
TOP_DIR=$(cd $(dirname "$0")/.. && pwd)
@@ -49,97 +53,110 @@
git clone -b rst_support https://github.com/dtroyer/shocco shocco
cd shocco
./configure
- make
+ make || exit
cd ..
fi
SHOCCO=$TOP_DIR/shocco/shocco
fi
# Process command-line args
-while getopts b:p c; do
+while getopts go: c; do
case $c in
- b) MASTER_BRANCH=$OPTARG
+ g) GH_UPDATE=1
;;
- p) PUSH_REPO=1
+ o) HTML_BUILD=$OPTARG
;;
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
+
+if [[ -n "$1" ]]; then
+ master="master"
+ if [[ "${master/#$1}" != "master" ]]; then
+ # Partial match on "master"
REPO=$MASTER_REPO
else
REPO=$1
fi
+ REPO_BRANCH=${2:-$MASTER_BRANCH}
fi
# Check out a specific DevStack branch
if [[ -n $REPO ]]; then
# Make a workspace
- TMP_ROOT=$(mktemp -d devstack-docs-XXXX)
+ TMP_ROOT=$(mktemp -d work-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
+ if [[ -n "$REPO_BRANCH" ]]; then
+ git checkout $REPO_BRANCH
+ fi
fi
+# Assumption is we are now in the DevStack workspace to be processed
+
# Processing
# ----------
-# Assumption is we are now in the DevStack repo workspace to be processed
+# Clean up build dir
+rm -rf $HTML_BUILD
+mkdir -p $HTML_BUILD
-# Pull the latest docs branch from devstack.org repo
-if ! [ -d docs ]; then
- git clone -b gh-pages $GH_PAGES_REPO docs
-fi
+# Get fully qualified dirs
+FQ_DOCS_SOURCE=$(cd $DOCS_SOURCE && pwd)
+FQ_HTML_BUILD=$(cd $HTML_BUILD && pwd)
+
+# Get repo static
+cp -pr $FQ_DOCS_SOURCE/* $FQ_HTML_BUILD
# 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
+ mkdir -p $FQ_HTML_BUILD/`dirname $f`;
+ $SHOCCO $f > $FQ_HTML_BUILD/$f.html
done
-for f in $(find functions lib samples -type f -name \*); do
+for f in $(find functions functions-common lib samples -type f -name \*); do
echo $f
FILES+="$f "
- mkdir -p docs/`dirname $f`;
- $SHOCCO $f > docs/$f.html
+ mkdir -p $FQ_HTML_BUILD/`dirname $f`;
+ $SHOCCO $f > $FQ_HTML_BUILD/$f.html
done
-echo "$FILES" >docs-files
+echo "$FILES" >docs/files
-# Switch to the gh_pages repo
-cd docs
+if [[ -n $GH_UPDATE ]]; then
+ GH_ROOT=$(mktemp -d work-gh-XXXX)
+ cd $GH_ROOT
-# Collect the new generated pages
-find . -name \*.html -print0 | xargs -0 git add
+ # Pull the latest docs branch from devstack.org repo
+ git clone -b gh-pages $GH_PAGES_REPO gh-docs
-# 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
+ # Get the generated files
+ cp -pr $FQ_HTML_BUILD/* gh-docs
+
+ # Collect the new generated pages
+ (cd gh-docs; 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
fi
# Clean up or report the temp workspace
if [[ -n REPO && -n $PUSH_REPO ]]; then
- rm -rf $TMP_ROOT
+ echo rm -rf $TMP_ROOT
else
if [[ -z "$TMP_ROOT" ]]; then
TMP_ROOT="$(pwd)"
fi
- echo "Built docs in $TMP_ROOT"
+ echo "Built docs in $HTML_BUILD"
fi