Publish the documentation as a site on Read the Docs (Zensical)

[allen0099]

Summary

The documentation is a set of Markdown files (README.md plus docs/*.md, around 2,800 lines) read on GitHub. Publish it as a documentation site that needs no infrastructure of our own to maintain.

Decision

• Hosting: Read the Docs (free for open source). Builds on every push, gives each pull request a preview build, keeps one build per released version, and includes search and a CDN. The only file to maintain is .readthedocs.yaml.
• Generator: Zensical, from the team behind Material for MkDocs. It reads the Markdown we already have, and Read the Docs documents it officially. Material for MkDocs itself enters maintenance mode on 2026-11-05 (fixes only, no new features), so it is not a good choice for a new site. Sphinx would mean rewriting the Markdown in reStructuredText.
• API reference: generated from the existing Google-style docstrings with mkdocstrings-python, which Zensical supports.

Plan

• zensical.toml with the navigation: home, guides (CACHE_FLOW, SESSION, JWT_CLAIMS, STATE), API reference, development (DEVELOPMENT, CONTRIBUTING), changelog.
• docs/index.md as the landing page. The GitHub README.md stays as-is, since PyPI renders it.
• A docs dependency group in pyproject.toml, so uv run zensical serve works locally.
• .readthedocs.yaml
• A CI job that builds the site, so a broken link or page fails the PR before Read the Docs sees it.
• Documentation URL in [project.urls] and a link in the README.
• Import the repository on readthedocs.org (maintainer, needs the GitHub account).

Open questions

• Zensical is still pre-1.0 (0.0.x at the time of writing), so the version should be pinned to a range and upgraded deliberately.
• Traditional Chinese: only the README has a translation (docs/README.zh-TW.md). Read the Docs handles translations as a separate linked project. Out of scope for the first version; the file stays where it is.

[allen0099]

The site is live at https://fastapi-cachex.readthedocs.io/en/latest/.

• docs: publish the documentation with Zensical on Read the Docs #82: Zensical config, API reference via mkdocstrings, docs dependency group, .readthedocs.yaml, the strict-build Docs workflow, and the Documentation URL.
• docs: publish every guide in English and bring them up to date #85: every guide in English and checked against the code. GitHub-style callouts now render on the site.

Deviations from the plan:

• README links: docs/index.md includes README.md through snippets instead of duplicating it. The README's relative links therefore became absolute GitHub URLs, because relative links inside an included file are not checked by --strict and broke on the site.
• README.zh-TW.md is out of the site navigation. The translation is tracked in 89 as a Read the Docs translation project.
• stable version: it points at tag v0.3.5, which predates .readthedocs.yaml, so its build fails. It will build with the next release. latest (the default) is unaffected.