rax-docs

#!/bin/bash -e

## This is a script to build docs projects started from the Docs Starter Kit.
## This is just a brief shim that relies on having the full repository installed in a project
## to function. This script handles that installation, and it passes other commands through to
## the underlying installation afterward.
##
## General rules:
## - CLI Commands map to function names. It either matches an allowed function in this script,
##   or it gets passed to the internal script.
## - Error handling is explicit. If some condition should cause failure, use "|| { failure stuff }"
##   to do so. The bash -e flag is set as a precaution, but its behavior is somewhat unreliable
##   when you need precision.
## - Functions and the internal script(s) signal a fatal error to this script with exit code 1.
##   They signal a user abort with exit code 2.
## - Git submodules are messy and impossible to fully remove once added to a repo; therefore I'm
##   avoiding them for now.
## - This wrapper script should be as foolproof as possible because it's intended to be
##   distributed into all of the docs projects, and finding and updating all the copies of it
##   will be difficult. This is exactly the problem that this independent toolkit is trying to
##   solve for all of the docs projects out there.

export RAX_DOCS_WRAPPER_VERSION=1
SCRIPTNAME=$(basename "$0")

## Perform a fresh install of the toolkit. This can be a first-time install, or it could be
## installing over itself. Installing over an installation should always work.
function install {
    echo "Welcome to the rax-docs toolkit."
    echo ""
    mkdir -p .rax-docs
    rm -rf .rax-docs/repo
    OUTPUT=$(git clone https://github.com/IDPLAT/rax-docs.git .rax-docs/repo 2>&1) || {
        echo "Failed to clone the full repo from GitHub. You'll need to fix this problem."
        echo ""
        echo "$OUTPUT"
        exit 1
    }
    [ -z "$1" ] || OUTPUT=$(git -C .rax-docs/repo checkout "$1" 2>&1) || {
	echo "Error checking out requested version."
	echo ""
	echo "The version you requested ($1) isn't a valid git treeish."
	echo "You need to specify a tag, branch, or commit hash to install."
	echo ""
	echo "$OUTPUT"
	return 1
    }
    .rax-docs/repo/internal/main internal_install "$@"
}

## Get the installed toolkit version. This is for when the toolkit has been installed in a
## project, but you, a team member, or Jenkins is working from a different clone of the repo.
## Using the configuration added during installation, this will download the right version of
## the toolkit repo so that docs can be built and tested.
function get {
    [ ! -f .rax-docs/config/bash ] && {
	echo "The config file .rax-docs/config/bash is missing."
	echo ""
	echo "Try installing the toolkit with '$SCRIPTNAME install <version>'."
	return 1
    }
    # shellcheck disable=SC1091
    source .rax-docs/config/bash || {
	echo ""
	echo "Failed to source the config file."
	return 1
    }
    [ -n "$JENKINS_URL" ] && {
	# shellcheck disable=SC1091
	source /opt/rh/rh-git29/enable || {
	    echo "Failed to activate latest git on Jenkins."
	    echo ""
	    echo "This script uses the -C flag, which the original Jenkins git version "
	    echo "didn't support. We need a newer git version which supports this flag."
	    exit 1
	}
    }
    rm -rf .rax-docs/repo
    OUTPUT=$(git clone https://github.com/IDPLAT/rax-docs.git .rax-docs/repo 2>&1) || {
	echo "Failed to clone the full repo from GitHub. You'll need to fix this problem."
	echo ""
	echo "$OUTPUT"
	return 1
    }
    OUTPUT=$(git -C .rax-docs/repo checkout "$TOOLKIT_VERSION" 2>&1) || {
	echo "Error checking out configured version."
	echo ""
	echo "The TOOLKIT_VERSION specified in your config may name a git treeish that"
	echo "doesn't exist anymore, or else something else bad happened."
	echo ""
	echo "$OUTPUT"
	return 1
    }
    echo "Got toolkit version $TOOLKIT_VERSION"
}

function tools_check {
    [ -f .rax-docs/config/bash ] && [ ! -d .rax-docs/repo ] && {
	echo "The toolkit is configured but not present."
	echo ""
	echo "Try running '$SCRIPTNAME get', and then try again."
	return 1
    }
    [ -d .rax-docs/repo ] || {
	echo "The toolkit hasn't been installed in this project."
	echo ""
	echo "Try running '$SCRIPTNAME install <version>'."
	return 1
    }
}

function update_check {
    mkdir -p .rax-docs/cache
    [ -d .rax-docs/repo ] || return 0
    # All timestamps are in seconds since epoch
    LAST_CHECK=$(stat -c %Y .rax-docs/cache/update_check 2>&1) || {
	# If there's no record of a check, it was probably just installed, so assume it's up
	# to date. This will also help prevent the update check from interfering with tests.
	LAST_CHECK=$(date +%s)
    }
    # Regardless of the outcome, only let this happen once per check period. If it fails because
    # github connections are timing out, doing it over and over until we succeed would make the
    # toolkit useless.
    touch .rax-docs/cache/update_check
    # Check for updates if not fetched the previous week
    NEXT_CHECK=$((LAST_CHECK + 604800))
    NOW=$(date +%s)
    if [ "$NOW" -gt "$NEXT_CHECK" ]; then
	git -C .rax-docs/repo fetch --prune --tags &> /dev/null || true
	MY_TS=$(stat -c %Y "$SCRIPTNAME")
	THEIR_TS_GIT=$(git -C .rax-docs/repo log -1 --pretty="format:%ci" origin/master -- rax-docs)
	THEIR_TS=$(date -d "$THEIR_TS_GIT" +%s)
	if [ "$MY_TS" -lt "$THEIR_TS" ]; then
	    echo "A new version of this script is available!"
	    echo ""
	    echo "It may have bugfixes or new features available."
	    echo ""
	    read -rp "Update now? [Y/n] "
	    if [ -z "$REPLY" ] || [[ "$REPLY" =~ ^[Yy].* ]]; then
		# Download to a temp location and then switch files
		# around. This is to hopefully prevent bash from
		# reloading the script immediately, which would likely
		# fail.
		TMP=$(mktemp)
		OUTPUT=$(wget -O "$TMP" https://raw.githubusercontent.com/IDPLAT/rax-docs/master/rax-docs 2>&1) || {
		    echo "Oops, downloading the latest version failed. Try again later!"
		    echo ""
		    echo "$OUTPUT"
		    echo ""
		    return 0
		}
		chmod --reference=rax-docs "$TMP"
		mv rax-docs "$TMP.old"
		mv "$TMP" rax-docs
		echo ""
		echo "Thanks for updating! Don't forget to commit the new script!"
	    fi
	    echo ""
	fi
    fi
}

update_check

if [ $# -eq 0 ]; then
     if [ -d .rax-docs/repo ]; then
	 .rax-docs/repo/internal/main usage
     else
	 echo "Try '$SCRIPTNAME install' to install the toolkit."
	 echo "For additional information, see the readme at"
	 echo "https://github.com/IDPLAT/rax-docs"
     fi
     exit 1
fi

TOPCMD="$1"
shift

# Keep track of function exits/returns to deal with them correctly.
EXIT=0
case $TOPCMD in
    install|get)
	$TOPCMD "$@" || EXIT=$?
	;;

    *)
	tools_check || EXIT=$?
	[ $EXIT -eq 0 ] && .rax-docs/repo/internal/main "$TOPCMD" "$@" || EXIT=$?
	;;
esac

RESULT="ended badly"
[ $EXIT -eq 0 ] && RESULT="completed"
[ $EXIT -eq 1 ] && RESULT="failed"
[ $EXIT -eq 2 ] && RESULT="completed" && EXIT=0

echo ""
echo "$TOPCMD command $RESULT"

exit $EXIT