make_docs

#!/bin/bash
#
# Build ksconf sphinx docs using a virtual environment.  Once complete, a
# browser window will open to view the docs locally.  Local changes will
# automatically trigger a refresh of the impacted pages.
#
# This script should work on Mac, Linux, and Windows using "Git Bash" or MINGW64
#
# Note that, to save time, the virtual environment for docs is cached and not
# rebuilt.  If stale, it may be necessary to simply delete that folder and then
# re-run this script.

set -e
VENV=venv_docs

if command -v python3 > /dev/null 2>&1; then
    PY=python3
else
    # Windows way of getting to python 3
    PY="py -3"
fi

# Make sure we have a sane environment (figure out version # and so on)
echo "Run setup.py"
python setup.py >/dev/null 2>&1 || true

INSTALL=0
if [[ ! -d "$VENV" ]]
then
    echo "Create a fresh virtual environment ($VENV)"
    $PY -m virtualenv "$VENV"
    INSTALL=1
fi

echo "Activating virtual environment ($VENV)"
# shellcheck disable=SC1090
if [[ -f "$VENV"/bin/activate ]]; then
    . "$VENV"/bin/activate
elif [[ -f "$VENV"/Scripts/activate ]]; then
    . "$VENV"/Scripts/activate
else
    echo "Can't activate virtual environment $VENV"
fi

if [[ $INSTALL -eq 1 ]]; then
    echo "Install required docs packages ($VENV)"
    $PY -m pip install -r requirements-doc.txt
fi

echo "Make dynamics docs"
$PY make_dyn_docs.py

echo "Running the autodoc extension"
rm -rf "docs/source/api"
sphinx-apidoc --force --implicit-namespaces -o "docs/source/api" ksconf ksconf/ext

echo "Building local html docs and opening browser window"
# Or, something like:   make html
LINKCHECK_ARGS=()

if [[ "z$LINKCHECK" != "z" ]]; then
    LINKCHECK_ARGS=(-b linkcheck)
fi

sphinx-autobuild --port 9999 --watch ksconf docs/source docs/build/html "${LINKCHECK_ARGS[@]}" --open-browser