Merge pull request jupyterhub#3051 from manics/linkcheck-summarise-ou…

…tput

Summarise linkcheck CI output

.github/workflows/test-docs.yaml

@@ -43,3 +43,8 @@ jobs:
         run: |
           cd docs
           make linkcheck SPHINXOPTS='--color -W --keep-going'
+
+      - name: summarise linkcheck issues
+        if: always()
+        run: |
+          ./ci/summarise-linkcheck-output ./docs/_build/linkcheck/output.json

ci/summarise-linkcheck-output

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Parse the output.json created by the Sphinx linkchecker
+# and summarise broken and redirected links
+
+set -eu
+LINKCHECK="$1"
+
+N_BROKEN=$(jq -r 'select(.status=="broken")' "$LINKCHECK" | jq -s length)
+N_PERMANENT_REDIRECT=$(jq -r 'select(.status=="redirected")' "$LINKCHECK" | jq -s length)
+
+# shellcheck disable=SC2086
+if [[ $N_BROKEN -gt 0 ]]; then
+    printf "\n\033[31;1m%s\033[0m\n" "Broken links"
+    jq -r 'select(.status=="broken") | "\(.filename):\(.lineno) \(.uri)\n    \(.info)"' "$LINKCHECK"
+fi
+
+# shellcheck disable=SC2086
+if [[ $N_PERMANENT_REDIRECT -gt 0 ]]; then
+    printf "\n\033[35;1m%s\033[0m\n" "Permanently redirected links"
+    jq -r 'select(.status=="redirected" and .code==301) | "\(.filename):\(.lineno) \(.uri)\n    \(.info)"' "$LINKCHECK"
+fi
+
+exit "$N_BROKEN"