Add the doc build tools

tools/build_docs.sh generates the devstack.org website from the static
pages and generated pages created by running shocco against a DevStack
checkout.

Note that while this is the complete auto page generation of the
devstack.org site, pushing the content back to GitHub is limited
to those with push access to the current repo.

Partial-bug 1235626

Change-Id: I61dc3d56e4a4832a9ddd1904dd8af65c15a17e50
This commit is contained in:
Dean Troyer 2013-10-16 15:13:56 -05:00
parent 79ad861710
commit 9b973670a6

135
tools/build_docs.sh Executable file
View File

@ -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