From 97dd166c9c35d525321ea4e741e374c67e24cdb3 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@lsst.org>
Date: Thu, 31 Aug 2023 17:13:54 -0700
Subject: [PATCH] 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 | 23 +++++++++++++++++++++++
 tox.ini  |  7 ++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 771f2d55..80eddb49 100644
--- a/Makefile
+++ b/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)
diff --git a/tox.ini b/tox.ini
index 53db32c8..68761334 100644
--- a/tox.ini
+++ b/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