Migrate documentation build from MkDocs to Zensical

[koxudaxi]

Summary

• Replace MkDocs with Zensical for documentation generation
  https://zensical.org/

Summary by CodeRabbit

• Chores
  • Switched documentation build tooling to a single new package with a Python 3.10+ requirement.
  • Updated build commands across CI, project config, and local tooling to use the new builder.
  • Adjusted documentation output paths printed and used by automation to match the new build layout.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Replaced documentation tooling from mkdocs to zensical: updated CI workflow, tox commands/paths, and pyproject dependency entry to reference zensical with a Python version constraint.

Changes

Cohort / File(s)	Summary
Documentation tooling migration .github/workflows/docs.yaml, pyproject.toml, tox.ini	Swapped mkdocs usage for zensical. CI workflow command changed from mkdocs build --verbose --clean --strict to zensical build --clean. pyproject.toml dependency-group docs replaced ["mkdocs>=1.6", "mkdocs-material>=9.5.31"] with ["zensical>=0.0.11; python_version>='3.10'"]. tox build invocation and printed output path updated from env_tmp_dir to {tox_root}/site/index.html (or {tox_root}/site).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review the exact zensical CLI flags used (--clean vs prior flags) and ensure behavior parity.
• Verify pyproject.toml marker (python_version>='3.10') matches project CI/test matrix.
• Confirm tox {tox_root}/site is the actual zensical output path and update any downstream consumers or URLs if needed.
• Check GitHub Actions workflow for any implicit assumptions about mkdocs-specific outputs or environment variables.

Poem

🐰 I hopped from mkdocs' familiar den,
To zensical meadows—new paths again.
Build flags changed and site paths too,
A tidy hop, a doc-refreshing view.
Pocket full of bytes, I bounce—whee! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title directly and clearly describes the main change: migrating the documentation build tool from MkDocs to Zensical, which aligns with all modified files (.github/workflows/docs.yaml, pyproject.toml, tox.ini) that reflect this exact tooling replacement.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch migrate-docs-to-zensical

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8da7008 and 60f057f.

📒 Files selected for processing (1)

• .github/workflows/docs.yaml (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/docs.yaml

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)

• GitHub Check: 3.14 on macOS
• GitHub Check: 3.11 on Windows
• GitHub Check: 3.14 on Windows
• GitHub Check: 3.9 on macOS
• GitHub Check: 3.13 on Windows
• GitHub Check: 3.10 on macOS
• GitHub Check: 3.12 on Windows
• GitHub Check: 3.9 on Windows
• GitHub Check: 3.11 on macOS
• GitHub Check: 3.10 on Windows
• GitHub Check: benchmarks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c8f8744 and 8da7008.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• .github/workflows/docs.yaml (1 hunks)
• pyproject.toml (1 hunks)
• tox.ini (1 hunks)

🔇 Additional comments (2)

tox.ini (1)

125-126: LGTM! Documentation path updated correctly.

The build command and output path are properly updated to reflect zensical's behavior, aligning with the GitHub workflow changes.

pyproject.toml (1)

105-105: Evaluate risk of pre-release dependency before adoption.

Zensical is in alpha/development (0.0.x versioning) and approaching beta release, created by the Material for MkDocs team as a modern replacement for the unmaintained MkDocs. While designed to be compatible with Material for MkDocs and supporting Python Markdown without content changes, feature parity with Material for MkDocs is still a work in progress. Assess whether gaps in plugin support and ongoing development align with your documentation requirements before production deployment.

[codspeed-hq]

CodSpeed Performance Report

Merging #2679 will not alter performance

_{Comparing migrate-docs-to-zensical (60f057f) with main (c8f8744)}

Summary

✅ 52 untouched
⏩ 10 skipped¹

Footnotes

1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.52%. Comparing base (c8f8744) to head (60f057f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2679   +/-   ##
=======================================
  Coverage   99.52%   99.52%           
=======================================
  Files          79       79           
  Lines       11172    11172           
  Branches     1348     1348           
=======================================
  Hits        11119    11119           
  Misses         32       32           
  Partials       21       21           

Flag	Coverage Δ
unittests	99.52% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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