Autobuild docs on file changes

Annoyed by alt-tab and up-enter interactions, I submit this simple script to
watch for change on the filesystem and automatically run `make html`.  At which
point, it runs every time any file is modified in docs/, and all the dev need
do is reload the relevant page in the browser.

Only caveat is that the script looks for changes _in the git index_.  So new
files that have not yet been added to git's watch list won't be considered.
(Simple fix == `git add <docs/your/new/file>`)

With thanks to Chris for testing macOS usage.

Makefile

@@ -1,5 +1,5 @@
 .venv-docs:
-	python -m venv .venv-docs
+	python3 -m venv .venv-docs
 	.venv-docs/bin/pip install -U pip setuptools
 	.venv-docs/bin/pip install './compute_sdk[docs]' './compute_endpoint'
 

docs/autobuild.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# Take advantage of FS-events to avoid an up-enter cycle.  Just save any file within
+# the documentation directory and then go reload the page.
+#
+# N.B.: difference must be visible via `git diff`; new files won't get picked up unless
+# at least added to the git index.
+
+PORT="${1:-12345}"
+
+renice -n +1000 -p $$
+command -v ionice &> /dev/null && ionice -c 2 -n 7 -p $$
+
+doc_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+cd "$doc_dir" || { echo "Unable to change directory to '$doc_dir';"; exit 2; }
+
+dev_venvs=(  # add dev-specific venvs activate paths here
+    ../venvs/gcdocs/bin/activate
+    ../.venv-docs/bin/activate  # created by ../Makefile (`make docs`)
+)
+for venv_activate in "${dev_venvs[@]}"; do
+    [[ -f "$venv_activate" ]] && {
+        source "$venv_activate" || exit 2
+        _ACTIVATED=1
+        break
+    }
+done
+
+if [[ -z $_ACTIVATED ]]; then
+    (cd ..; make .venv-docs) || exit 2
+    source ../.venv-docs/bin/activate || exit 2
+else
+    python -m pip install -U pip setuptools || exit 2
+    python -m pip install -e '../compute_sdk[docs]' -e '../compute_endpoint' || exit 2
+fi
+
+# inaugural run
+make clean html || exit 2
+
+# quick and dirty display clean up from inaugural run; highlight python
+# 'http.server' message
+echo -en "\033[;H\033[J\033[40;92;1m"
+(cd _build/html/; python3 -m http.server -b 127.0.0.1 $PORT) &
+sleep 1
+echo -en "\033[m"
+
+P="$(git diff)"  # "previous"
+while : ; do
+    echo -en "\033[G\033[K$(date) Settling ..."
+    sleep 3  # Just give some settling time
+    echo -en "\033[G\033[K$(date) Waiting for changes ..."
+    inotifywait -re modify ./ &> /dev/null
+    N="$(git diff)"  # "now"
+    [[ $N = "$P" ]] && continue  # don't waste cycles if no worthy change
+    echo -en "\033[G\033[K"
+    P="$N"
+    make html
+    echo -e "\n"
+done