Merge pull request #191 from lsst-sqre/tickets/DM-40495

DM-40495: Improve error reporting from docs-linkcheck

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