Migrate docs to Zensical and deploy via GitHub Actions

[will-ockmore]

Summary

Migrates the documentation from Material for MkDocs to Zensical (the successor built by the same team) and modernizes GitHub Pages publishing to a first-party GitHub Actions deployment. Closes #73.

This also resolves the class of failure seen recently where the docs deploy failed with a generic "Deployment failed, try again later" — that came from GitHub's hidden legacy pages-build-deployment workflow triggered by pushing to the gh-pages branch. The deploy now runs in our workflow, with visible logs and trivial re-runs.

What changed

Docs → Zensical

• Add zensical.toml (replacing mkdocs.yml) with equivalent nav, deep-purple palette, light/dark toggle, and the markdown extensions the content actually uses (admonition, details, superfences, footnotes, highlight).
• mkdocstrings still auto-generates the API reference — all 20 API symbols render identically and cross-references resolve (the mkdocstrings-linking gap noted in httpx forks - is the library compatible? #73 is now supported in Zensical).
• Swap the mkdocs-material dev dependency for zensical.
• scripts/build now runs zensical build --clean --strict.
• Small polish: title: API front matter so the API page heading reads "API"; docs/stylesheets/extra.css to drop the underline on the badge links.

Pages → GitHub Actions (after a successful release)

• Add .github/workflows/docs.yml: build with Zensical and deploy via configure-pages / upload-pages-artifact / deploy-pages. Actions are SHA-pinned to match repo convention.
• Triggers via workflow_run after the Publish workflow completes successfully (Publish runs on version tags and pushes to PyPI), so docs deploy only after a release actually succeeds — never in parallel with it. Manual workflow_dispatch is kept for first-time/one-off deploys. The docs job checks out the released commit (workflow_run.head_sha) so the site matches the release.
• Removes docs publishing from scripts/publish (dropped mkdocs gh-deploy --force). There was no separate "old Pages workflow" file: the previous deploy pushed the built site to the gh-pages branch, and GitHub's implicit pages-build-deployment ran off the legacy "deploy from branch" source. Switching the Pages source to GitHub Actions (below) retires that implicit workflow.

Functional equivalence

No degradation — verified by diffing rendered output against the current Material build and rendering pages in a browser:

Check	Result
Pages built	8/8
API symbols (mkdocstrings)	20/20 identical
Admonitions / footnotes / collapsible details	✅ render
Code highlighting (Pygments)	✅ (now with language classes)
Cross-references (autorefs)	✅ (2 extra valid refs resolved)
Deep-purple palette + dark mode	✅
Search	✅ (Zensical "Disco" engine)
objects.inv inventory	✅ preserved

Local checks: strict build clean, dev server (zensical serve) serves all pages, 152 tests pass at 100% coverage, lint clean.

⚠️ One-time setup on merge

• workflow_run only fires once docs.yml is on the default branch, so the release-triggered deploy activates after this PR merges.
• The workflow runs actions/configure-pages with enablement: true, which should switch the Pages source from the gh-pages branch to GitHub Actions on the first run. If it doesn't, set Settings → Pages → Build and deployment → Source → GitHub Actions once. The old gh-pages branch can be deleted afterward.
• To publish docs immediately (without cutting a release), use the workflow's manual Run workflow button (workflow_dispatch).

Note (out of scope)

Issue #73 also suggests moving off httpx to httpxyz. That changes the library's runtime dependency (not just docs) and the thread concluded it's premature — deliberately left out of this PR.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (a7aa1f3) to head (61d8e2b).

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #81   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            8         8           
  Lines         1460      1460           
=========================================
  Hits          1460      1460           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.