Migrate docs from mkdocs-material to Zensical (#343)

mkdocs-material has entered maintenance mode in favor of Zensical, which
is built by the same team and reads mkdocs.yml directly. This swaps the
docs dependencies and build command accordingly.

Also removes a stale top-level sitecustomize.py that snuck in with #170,
adds site/ to .gitignore, and updates the README with current
Redis/Valkey test versions and a note on working with docs locally.

Closes #273

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: chrisguidry

.coveragerc-cli

@@ -6,4 +6,5 @@ parallel = true
 include =
     src/docket/cli/*
     tests/cli/*
+    tests/sitecustomize.py
 exclude_also = ["\\.\\.\\.$"]

.coveragerc-core

@@ -10,6 +10,7 @@ omit =
     **/conftest.py
     tests/_key_leak_checker.py
     tests/_container.py
+    tests/sitecustomize.py
     tests/cli/*.py
 
 [report]

.github/workflows/docs.yml

@@ -39,7 +39,7 @@ jobs:
         run: uv sync --group docs
 
       - name: Build documentation
-        run: uv run mkdocs build
+        run: uv run zensical build
 
       - name: Upload artifact
         uses: actions/upload-artifact@v6

.gitignore

@@ -8,6 +8,7 @@
 __pycache__/
 build/
 dist/
+site/
 wheels/
 
 .coverage.*

README.md

@@ -84,8 +84,8 @@ pip install pydocket
 Docket requires a [Redis](http://redis.io/) server with Streams support (which was
 introduced in Redis 5.0.0). Docket is tested with:
 
-- Redis 6.2, 7.4, and 8.0 (standalone and cluster modes)
-- [Valkey](https://valkey.io/) 8.0
+- Redis 6.2, 7.4, and 8.6 (standalone and cluster modes)
+- [Valkey](https://valkey.io/) 8.1
 - In-memory backend via [fakeredis](https://github.com/cunla/fakeredis-py) for testing
 
 For testing without Redis, use the in-memory backend:
@@ -120,3 +120,13 @@ believe that `docket` should stay small, simple, understandable, and reliable, a
 begins with testing all the dusty branches and corners. This will give us the
 confidence to upgrade dependencies quickly and to adapt to new versions of Redis over
 time.
+
+To work on the documentation locally:
+
+```bash
+uv sync --group docs
+uv run zensical serve
+```
+
+This will start a local preview server. The docs are built with
+[Zensical](https://zensical.dev/) and configured in `mkdocs.yml`.

pyproject.toml

@@ -75,9 +75,8 @@ dev = [
 ]
 
 docs = [
-    "mkdocs>=1.5.3",
-    "mkdocs-material>=9.7.1",
-    "mkdocstrings>=0.24.1",
+    "zensical",
+    "mkdocstrings>=1.0.2",
     "mkdocstrings-python>=2.0.1",
 ]
 examples = [
@@ -145,6 +144,8 @@ omit = [
     # Test infrastructure with conditional branches for cluster/standalone
     "tests/_key_leak_checker.py",
     "tests/_container.py",
+    # Subprocess coverage hook, exercised by CLI tests only
+    "tests/sitecustomize.py",
 ]
 branch = true
 parallel = true

tests/cli/run.py

@@ -29,12 +29,10 @@ async def run_cli(
     if has_pytest_cov:
         argv = [same_python, "-m", "docket", *args]  # pragma: no cover
     else:
-        # Try sitecustomize auto-start first
         merged_env.setdefault("COVERAGE_PROCESS_START", "pyproject.toml")
-        # Ensure *this repo* (where sitecustomize.py lives) is on PYTHONPATH
-        repo_root = os.path.abspath(os.getcwd())
+        tests_dir = os.path.join(os.path.abspath(os.getcwd()), "tests")
         merged_env["PYTHONPATH"] = os.pathsep.join(
-            [repo_root, merged_env.get("PYTHONPATH", "")]
+            [tests_dir, merged_env.get("PYTHONPATH", "")]
         )
         argv = [same_python, "-m", "docket", *args]
 

sitecustomize.py tests/sitecustomize.pysitecustomize.py renamed to tests/sitecustomize.py

@@ -1,4 +1,3 @@
-# This file ensures that we can collect coverage data for the CLI when it's running in a subprocess
 import os
 
 if os.getenv("COVERAGE_PROCESS_START"):