add pytest-check-links

Author: bollwyvl

ci/job.docs.yml

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

docs/conf.py

@@ -88,10 +88,10 @@
     "gh": (f"{github_url}/%s", "GitHub: "),
 }
 
-html_show_sourcelink = True  # True will show link to source
+html_show_sourcelink = True
 
 html_context = {
-    "display_github": True,
+    "display_github": False,
     "github_user": github_repo_org,
     "github_repo": github_repo_name,
     "github_version": "master",

requirements/docs.txt

@@ -2,6 +2,7 @@
 -r dev.txt
 graphviz
 nbsphinx
+pytest-check-links
 recommonmark
 sphinx
 sphinx_autodoc_typehints

requirements/docs.yml

@@ -7,6 +7,7 @@ channels:
 dependencies:
   - nbsphinx
   - pandas
+  - pytest
   - python-graphviz
   - recommonmark
   - sphinx
@@ -15,4 +16,5 @@ dependencies:
   - sphinx-autodoc-typehints
   - sphinx-copybutton
   - pip:
+      - pytest-check-links
       - sphinx-markdown-tables

scripts/docs.py

@@ -1,24 +1,36 @@
 """ antidisinformationarianism
 """
+import shutil
 import sys
 from pathlib import Path
 from subprocess import check_call
+from tempfile import TemporaryDirectory
 
 ROOT = Path(__file__).parent.parent
 DOCS = ROOT / "docs"
 
 
-def docs(watch=False):
+def docs(watch=False, check=False):
     """ build (and test) docs.
 
         because readthedocs, this gets called twice from inside sphinx
     """
     if watch:
         check_call(["sphinx-autobuild", ".", "_build"], cwd=DOCS)
-    else:
-        check_call(["sphinx-build", "-M", "html", ".", "_build"], cwd=DOCS)
+        return 0
+
+    if check:
+        # 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)
+
+    check_call(["sphinx-build", "-M", "html", ".", "_build"], cwd=DOCS)
     return 0
 
 
 if __name__ == "__main__":
-    sys.exit(docs(watch="--watch" in sys.argv))
+    sys.exit(docs(watch="--watch" in sys.argv, check="--check" in sys.argv))