Add separate workflow for docs build

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+---
+name: Check documentation
+
+on:
+  schedule:
+    - cron: "0 1 * * *" # everyday at 1am
+  push:
+    paths:
+      - "**.rst"
+      - "docs/**"
+  pull_request:
+    paths:
+      - "**.rst"
+      - "docs/**"
+
+jobs:
+  docs:
+    name: Build documentation & check links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+      - uses: actions/[email protected]
+        with:
+          python-version: "3.10"
+      - run: |
+          pip install --constraint=.github/workflows/constraints.txt pip
+          pip install --constraint=.github/workflows/constraints.txt nox
+      - name: Build documentation
+        run: nox --force-color --session=docs-build
+      - name: Upload documentation
+        uses: actions/[email protected]
+        with:
+          name: docs
+          path: docs/_build

.github/workflows/tests.yml

@@ -26,7 +26,6 @@ jobs:
           - { python: "3.10", os: "macos-latest", session: "tests" }
           # - { python: "3.10", os: "ubuntu-latest", session: "typeguard" }
           - { python: "3.10", os: "ubuntu-latest", session: "xdoctest" }
-          - { python: "3.10", os: "ubuntu-latest", session: "docs-build" }
 
     env:
       NOXSESSION: ${{ matrix.session }}
@@ -91,13 +90,6 @@ jobs:
           name: coverage-data
           path: ".coverage.*"
 
-      - name: Upload documentation
-        if: matrix.session == 'docs-build'
-        uses: actions/[email protected]
-        with:
-          name: docs
-          path: docs/_build
-
   coverage:
     runs-on: ubuntu-latest
     needs: tests

noxfile.py

@@ -1,4 +1,6 @@
 """Nox sessions."""
+import os
+import shlex
 import shutil
 import sys
 from pathlib import Path
@@ -40,13 +42,37 @@ def activate_virtualenv_in_precommit_hooks(session: Session) -> None:
     Args:
         session: The Session object.
     """
-    if session.bin is None:
-        return
+    assert session.bin is not None  # noqa: S101
+
+    # Only patch hooks containing a reference to this session's bindir. Support
+    # quoting rules for Python and bash, but strip the outermost quotes so we
+    # can detect paths within the bindir, like <bindir>/python.
+    bindirs = [
+        bindir[1:-1] if bindir[0] in "'\"" else bindir
+        for bindir in (repr(session.bin), shlex.quote(session.bin))
+    ]
 
     virtualenv = session.env.get("VIRTUAL_ENV")
     if virtualenv is None:
         return
 
+    headers = {
+        # pre-commit < 2.16.0
+        "python": f"""\
+            import os
+            os.environ["VIRTUAL_ENV"] = {virtualenv!r}
+            os.environ["PATH"] = os.pathsep.join((
+                {session.bin!r},
+                os.environ.get("PATH", ""),
+            ))
+            """,
+        # pre-commit >= 2.16.0
+        "bash": f"""\
+            VIRTUAL_ENV={shlex.quote(virtualenv)}
+            PATH={shlex.quote(session.bin)}"{os.pathsep}$PATH"
+            """,
+    }
+
     hookdir = Path(".git") / "hooks"
     if not hookdir.is_dir():
         return
@@ -55,30 +81,24 @@ def activate_virtualenv_in_precommit_hooks(session: Session) -> None:
         if hook.name.endswith(".sample") or not hook.is_file():
             continue
 
+        if not hook.read_bytes().startswith(b"#!"):
+            continue
+
         text = hook.read_text()
-        bindir = repr(session.bin)[1:-1]  # strip quotes
-        if not (
+
+        if not any(
             Path("A") == Path("a") and bindir.lower() in text.lower() or bindir in text
+            for bindir in bindirs
         ):
             continue
 
         lines = text.splitlines()
-        if not (lines[0].startswith("#!") and "python" in lines[0].lower()):
-            continue
-
-        header = dedent(
-            f"""\
-            import os
-            os.environ["VIRTUAL_ENV"] = {virtualenv!r}
-            os.environ["PATH"] = os.pathsep.join((
-                {session.bin!r},
-                os.environ.get("PATH", ""),
-            ))
-            """
-        )
 
-        lines.insert(1, header)
-        hook.write_text("\n".join(lines))
+        for executable, header in headers.items():
+            if executable in lines[0].lower():
+                lines.insert(1, dedent(header))
+                hook.write_text("\n".join(lines))
+                break
 
 
 @session(name="pre-commit", python="3.10")
@@ -170,8 +190,18 @@ def xdoctest(session: Session) -> None:
 
 @session(name="docs-build", python="3.10")
 def docs_build(session: Session) -> None:
-    """Build the documentation."""
-    args = session.posargs or ["docs", "docs/_build"]
+    """Build the documentation with linkcheck."""
+    args = session.posargs or [
+        "-b",
+        "linkcheck",
+        "-W",
+        "--keep-going",
+        "docs",
+        "docs/_build",
+    ]
+    if not session.posargs and "FORCE_COLOR" in os.environ:
+        args.insert(0, "--color")
+
     session.install(".")
     session.install("sphinx", "sphinx-click", "furo")