docs for link checking, only test internal links in CI

Author: bollwyvl

CONTRIBUTING.md

@@ -135,6 +135,21 @@ To watch documentation sources and build continuously:
 python scripts/docs.py --watch
 ```
 
+To check internal links in the docs after building:
+
+```bash
+python scripts/docs.py --check --local-only
+```
+
+To check internal _and_ external links in the docs after building:
+
+```bash
+python scripts/docs.py --check
+```
+
+> Note: you may get spurious failures due to rate limiting, especially in CI,
+> but it's good to test locally
+
 ### Browser-based Acceptance Tests
 
 The browser tests will launch JupyterLab on a random port and exercise the

ci/job.docs.yml

@@ -40,5 +40,5 @@ jobs:
                   targetPath: docs/_build
                   artifactName: Docs $(Build.BuildId)
 
-              - script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py --check
-                displayName: check URLs in docs
+              - script: ${{ platform.activate }} jupyterlab-lsp && python scripts/docs.py --check --local-only
+                displayName: check local URLs in docs

scripts/docs.py

@@ -3,34 +3,53 @@
 import shutil
 import sys
 from pathlib import Path
-from subprocess import check_call
+from subprocess import call
 from tempfile import TemporaryDirectory
 
 ROOT = Path(__file__).parent.parent
 DOCS = ROOT / "docs"
 
+CHECK_INI = """
+[pytest]
+addopts =
+    --check-links
+    -k "not ipynb {extra_k}"
 
-def docs(watch=False, check=False):
+junit_family = xunit2
+
+filterwarnings =
+    ignore::PendingDeprecationWarning
+"""
+
+
+def docs(watch=False, check=False, local_only=False):
     """ build (and test) docs.
 
         because readthedocs, this gets called twice from inside sphinx
     """
     if watch:
-        check_call(["sphinx-autobuild", ".", "_build"], cwd=DOCS)
-        return 0
+        return call(["sphinx-autobuild", ".", "_build"], cwd=DOCS)
 
-    if check:
+    elif check:
+        ini = CHECK_INI.format(extra_k="and not http" if local_only else "")
         # do this in a temporary directory to avoid surprises
         with TemporaryDirectory() as td:
             tdp = Path(td)
             dest = tdp / "a" / "deep" / "path"
             dest.parent.mkdir(parents=True)
-            shutil.copytree(DOCS / "_build", dest)
-            check_call(["pytest-check-links", "-vv", "-k", "not ipynb"], cwd=dest)
+            shutil.copytree(DOCS / "_build" / "html", dest)
+            (dest / "pytest.ini").write_text(ini)
 
-    check_call(["sphinx-build", "-M", "html", ".", "_build"], cwd=DOCS)
-    return 0
+            return call(["pytest"], cwd=dest)
+    else:
+        return call(["sphinx-build", "-M", "html", ".", "_build"], cwd=DOCS)
 
 
 if __name__ == "__main__":
-    sys.exit(docs(watch="--watch" in sys.argv, check="--check" in sys.argv))
+    sys.exit(
+        docs(
+            watch="--watch" in sys.argv,
+            check="--check" in sys.argv,
+            local_only="--local-only" in sys.argv,
+        )
+    )