Improve error reporting from docs-linkcheck

Sphinx doesn't summarize the linkcheck errors at the end of the
output, but it does write them to output.txt. Move the link checking
to a makefile target so that we can use shell trickery to output the
contents of that file on link checking failures.

Add help and clean targets to the Makefile, and remove docs/api when
building docs to avoid stale files left-over from automodsumm.

Makefile

@@ -1,6 +1,29 @@
+.PHONY: help
+help:
+	@echo "Make targets for Safir:"
+	@echo "make clean - Remove generated files"
+	@echo "make init - Set up dev environment (install pre-commit hooks)"
+	@echo "make linkcheck - Check for broken links in documentation"
+
+.PHONY: clean
+clean:
+	rm -rf .tox
+	rm -rf docs/_build
+	rm -rf docs/api
+
 .PHONY: init
 init:
 	pip install --upgrade pip tox tox-docker pre-commit
 	pip install --upgrade -e ".[arq,db,dev,gcs,kubernetes]"
 	pre-commit install
 	rm -rf .tox
+
+# This is defined as a Makefile target instead of only a tox command because
+# if the command fails we want to cat output.txt, which contains the
+# actually useful linkcheck output. tox unfortunately doesn't support this
+# level of shell trickery after failed commands.
+.PHONY: linkcheck
+linkcheck:
+	sphinx-build --keep-going -n -W -T -b linkcheck docs	\
+	    docs/_build/linkcheck				\
+	    || (cat docs/_build/linkcheck/output.txt; exit 1)

tox.ini

@@ -78,10 +78,15 @@ commands = pre-commit run --all-files
 
 [testenv:docs]
 description = Build documentation (HTML) with Sphinx.
+allowlist_externals =
+    rm
 commands =
+    rm -rf docs/api
     sphinx-build -W --keep-going -n -T -b html -d {envtmpdir}/doctrees docs docs/_build/html
 
 [testenv:docs-linkcheck]
 description = Check links in the documentation.
+allowlist_externals =
+    make
 commands =
-    sphinx-build --keep-going -n -W -T -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/linkcheck
+    make linkcheck