Fail workflow on documentation build failures

The documentation-build script did not propagate failures from
individual lines, which meant that a failure in the script could still
result in an attempted empty deployment, which deletes the whole website.
This ensures that the bash script propagates the failure through to the
workflow status, so the deployment does not trigger.

We also fix the failure that took out the website last time - a missing
transitive dependency (which isn't our fault, but is easy to work
around).

buildPublishable.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/bash
 
+set -eux -o pipefail
+
 ## This script builds the publishable version of the specification including
 ## all stable branches. Each is built successively in the normal way after
 ## a `git checkout` of the found stable branches. Each built stable version is
@@ -16,20 +18,20 @@ echo "Searching for stable branches with repo path refs/${repoPath}/stable/"
 origBranch=$(git symbolic-ref --short HEAD)
 
 echo "Checking if the current branch ${origBranch} is clean"
-if [ ! -z "$(git status --untracked-files=no --porcelain)" ]; then 
+if [ -n "$(git status --untracked-files=no --porcelain)" ]; then
   # Uncommitted changes in tracked files
   echo "  ERROR: Some files that have been changed are not committed!"
   echo "  This script will fail to generate a publishable build until everything has been committed"
   git status
-  exit -1
+  exit 1
 fi
 
 # initialize the destination folder
-mkdir -p ${destDir}/versions
+mkdir -p "${destDir}/versions"
 
 # Build the stable version list
-unset versionList
-for branch in `git for-each-ref --format='%(refname:short)' --sort=-refname refs/${repoPath}/stable/`; do
+versionList=""
+for branch in $(git for-each-ref --format='%(refname:short)' --sort=-refname "refs/${repoPath}/stable/"); do
   versionNum=${branch/*stable\//}
 
   if [ -z "${versionList}" ]
@@ -42,27 +44,27 @@ done
 
 # Now build each stable version and copy to destination folder
 echo "VersionList is ${versionList}"
-for branch in `git for-each-ref --format='%(refname:short)' --sort=-refname refs/${repoPath}/stable/`; do
+for branch in $(git for-each-ref --format='%(refname:short)' --sort=-refname "refs/${repoPath}/stable/"); do
   versionNum=${branch/*stable\//}
   
   echo "Checkout stable branch ${branch} with version number ${versionNum}"
-  git checkout ${branch}
+  git checkout "${branch}"
 
   # build
   VERSION=${versionNum} VERSION_LIST=${versionList} make html
 
   echo "Copy to publish dir ${destDir}/versions/${versionNum}"
-  cp -r build/html ${destDir}/versions/${versionNum}
+  cp -r build/html "${destDir}/versions/${versionNum}"
 done
 
 echo "Getting live branch ${liveBranch}"
-git checkout origin/${liveBranch}
+git checkout "origin/${liveBranch}"
 
 # build
 VERSION_LIST=${versionList} make html
 
 echo "Copy to publish dir"
-cp -r build/html/* ${destDir}
+cp -r build/html/* "${destDir}"
 
 echo "Restoring to ${origBranch}"
-git checkout ${origBranch}
+git checkout "${origBranch}"

requirements.txt

@@ -3,3 +3,7 @@ sphinxcontrib-bibtex
 openqasm_pygments~=0.1.0
 pylint
 reno
+
+# `sphinxcontrib-bibtex` uses `pkg_resources` from `setuptools` but fails
+# to specify it as an actual runtime dependency, so we do it for them.
+setuptools