@@ -158,6 +158,16 @@ build_msg() {
158158 echo -e "${_Blue}${tag:0:10}${_creset}$*"
159159}
160160
161+dump_return() {
162+
163+ # Use this as last command in your function to prompt an ERROR message if
164+ # the exit code is not zero.
165+
166+ local err=$1
167+ [ "$err" -ne "0" ] && err_msg "${FUNCNAME[1]} exit with error ($err)"
168+ return "$err"
169+}
170+
161171clean_stdin() {
162172 if [[ $(uname -s) != 'Darwin' ]]; then
163173 while read -r -n1 -t 0.1; do : ; done
@@ -699,6 +709,94 @@ pyenv.cmd() {
699709 )
700710}
701711
712+# Sphinx doc
713+# ----------
714+
715+GH_PAGES="build/gh-pages"
716+DOCS_DIST="${DOCS_DIST:=dist/docs}"
717+DOCS_BUILD="${DOCS_BUILD:=build/docs}"
718+
719+docs.html() {
720+ build_msg SPHINX "HTML ./docs --> file://$(readlink -e "$(pwd)/$DOCS_DIST")"
721+ pyenv.install
722+ docs.prebuild
723+ # shellcheck disable=SC2086
724+ PATH="${PY_ENV_BIN}:${PATH}" pyenv.cmd sphinx-build \
725+ ${SPHINX_VERBOSE} ${SPHINXOPTS} \
726+ -b html -c ./docs -d "${DOCS_BUILD}/.doctrees" ./docs "${DOCS_DIST}"
727+ dump_return $?
728+}
729+
730+docs.live() {
731+ build_msg SPHINX "autobuild ./docs --> file://$(readlink -e "$(pwd)/$DOCS_DIST")"
732+ pyenv.install
733+ docs.prebuild
734+ # shellcheck disable=SC2086
735+ PATH="${PY_ENV_BIN}:${PATH}" pyenv.cmd sphinx-autobuild \
736+ ${SPHINX_VERBOSE} ${SPHINXOPTS} --open-browser --host 0.0.0.0 \
737+ -b html -c ./docs -d "${DOCS_BUILD}/.doctrees" ./docs "${DOCS_DIST}"
738+ dump_return $?
739+}
740+
741+docs.clean() {
742+ build_msg CLEAN "docs -- ${DOCS_BUILD} ${DOCS_DIST}"
743+ # shellcheck disable=SC2115
744+ rm -rf "${GH_PAGES}" "${DOCS_BUILD}" "${DOCS_DIST}"
745+ dump_return $?
746+}
747+
748+docs.prebuild() {
749+ # Dummy function to run some actions before sphinx-doc build gets started.
750+ # This finction needs to be overwritten by the application script.
751+ true
752+ dump_return $?
753+}
754+
755+# shellcheck disable=SC2155
756+docs.gh-pages() {
757+
758+ # The commit history in the gh-pages branch makes no sense, the history only
759+ # inflates the repository unnecessarily. Therefore a *new orphan* branch
760+ # is created each time we deploy on the gh-pages branch.
761+
762+ docs.clean
763+ docs.prebuild
764+ docs.html
765+
766+ [ "$VERBOSE" = "1" ] && set -x
767+ local head="$(git rev-parse HEAD)"
768+ local branch="$(git name-rev --name-only HEAD)"
769+ local remote="$(git config branch."${branch}".remote)"
770+ local remote_url="$(git config remote."${remote}".url)"
771+
772+ # prepare the *orphan* gh-pages working tree
773+ (
774+ git worktree remove -f "${GH_PAGES}"
775+ git branch -D gh-pages
776+ ) &> /dev/null || true
777+ git worktree add --no-checkout "${GH_PAGES}" origin/master
778+
779+ pushd "${GH_PAGES}" &> /dev/null
780+ git checkout --orphan gh-pages
781+ git rm -rfq .
782+ popd &> /dev/null
783+
784+ cp -r "${DOCS_DIST}"/* "${GH_PAGES}"/
785+ touch "${GH_PAGES}/.nojekyll"
786+ cat > "${GH_PAGES}/404.html" <<EOF
787+<html><head><META http-equiv='refresh' content='0;URL=index.html'></head></html>
788+EOF
789+
790+ pushd "${GH_PAGES}" &> /dev/null
791+ git add --all .
792+ git commit -q -m "gh-pages build from: ${branch}@${head} (${remote_url})"
793+ git push -f "${remote}" gh-pages
794+ popd &> /dev/null
795+
796+ set +x
797+ build_msg GH-PAGES "deployed"
798+}
799+
702800# golang
703801# ------
704802
@@ -1589,6 +1687,8 @@ if in_container; then
15891687 PY_ENV_BIN="${LXC_ENV_FOLDER}${PY_ENV_BIN}"
15901688 PYDIST="${LXC_ENV_FOLDER}${PYDIST}"
15911689 PYBUILD="${LXC_ENV_FOLDER}${PYBUILD}"
1690+ DOCS_DIST="${LXC_ENV_FOLDER}${DOCS_DIST}"
1691+ DOCS_BUILD="${LXC_ENV_FOLDER}${DOCS_BUILD}"
15921692fi
15931693
15941694lxc_init_container_env() {