docs: migrate to Zensical, refresh catalog

.github/workflows/docs.yml

@@ -1,16 +1,23 @@
 name: docs
 
+# The docs are hosted on Read the Docs (see .readthedocs.yaml).
+# This only checks that they build.
+
 on:
   push:
     branches:
       - main
+  pull_request:
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           python-version: 3.12
-      - run: uv run --group docs mkdocs gh-deploy --strict --force
+      - run: uv run --group docs python docs/_gen_catalog.py
+      - run: uv run --group docs zensical build --strict

.gitignore

@@ -97,7 +97,7 @@ ENV/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# docs build output
 /site
 
 # mypy
@@ -108,7 +108,10 @@ ENV/
 
 cmap/_version.py
 src/cmap/_version.py
-docs/assets/_data/
 
 .ruff_cache/
 uv.lock
+
+# generated docs (see docs/_gen_catalog.py)
+docs/catalog/*/
+.cache/

.pre-commit-config.yaml

@@ -12,6 +12,12 @@ repos:
       - id: pretty-format-json
         args: [--autofix]
 
+  - repo: https://github.com/adhtruong/mirrors-typos
+    rev: v1.51.1
+    hooks:
+      - id: typos
+        args: [--force-exclude] # omitting --write-changes
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.17.1
     hooks:

.readthedocs.yaml

@@ -1,4 +1,5 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# and https://docs.readthedocs.com/platform/stable/intro/zensical.html
 
 version: 2
 
@@ -10,7 +11,10 @@ build:
     post_install:
       - pip install uv
       - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --group docs --link-mode=copy
-
-mkdocs:
-  configuration: mkdocs.yml
-  fail_on_warning: true
+    build:
+      html:
+        - $READTHEDOCS_VIRTUALENV_PATH/bin/python docs/_gen_catalog.py
+        - $READTHEDOCS_VIRTUALENV_PATH/bin/zensical build --strict
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/