Skip to content

docs: publish the documentation with Zensical on Read the Docs - #82

Merged
allen0099 merged 2 commits into
masterfrom
docs/zensical-site
Sep 25, 2026
Merged

allen0099 merged 2 commits into
masterfrom
docs/zensical-site

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Part of #81. It does not close the issue, because the site only goes live once the Read the Docs project is imported and builds master.

What

  • zensical.toml builds a site from the existing guides:
    • an API reference generated by mkdocstrings from the Google-style docstrings (docs/api/*.md);
    • the README and CHANGELOG included through pymdownx.snippets, so each is written once.
  • Absolute links: relative links in README.md, docs/CONTRIBUTING.md and docs/README.zh-TW.md become absolute GitHub URLs. Links inside an included snippet resolve against the page that includes them and are not checked by --strict, so relative ones broke on the site. Absolute links also work on PyPI.
  • docs dependency group: zensical>=0.0.65,<0.1 and mkdocstrings-python. Zensical is pre-1.0, so upgrades should be deliberate. uv.lock gains only these packages.
  • Same strict build in two places: .readthedocs.yaml and a new Docs workflow both run zensical build --strict, so a broken link or docstring reference fails the PR instead of the published site.
  • [project.urls] gains a Documentation entry.

Notes

  • site_url is fixed to https://fastapi-cachex.readthedocs.io/, because Zensical cannot read READTHEDOCS_CANONICAL_URL. It must match the Read the Docs project slug.
  • CACHE_FLOW.md, JWT_CLAIMS.md and part of SESSION.md are in Chinese. They are published as-is; translating them is out of scope for Publish the documentation as a site on Read the Docs (Zensical) #81.

Verification

  • zensical build --strict: no issues, including in a clean environment set up with uv sync --frozen --only-group docs --no-install-project, the same command CI and Read the Docs run.
  • The API pages render: 15 class blocks on the Backends page.
  • The pre-commit suite passes. The uv-lock hook was skipped, because it upgrades unrelated dependencies; uv lock --check passes.

The guides under docs/ were only readable as raw Markdown on GitHub and
the API had no reference beyond the source. Build a site from them with
Zensical and host it on Read the Docs, which needs no server of our own
and builds PR previews.

- zensical.toml: navigation over the existing guides, an API reference
  generated by mkdocstrings from the Google-style docstrings, and the
  README/CHANGELOG pulled in with snippets so they are written once.
- README.md, CONTRIBUTING.md, README.zh-TW.md: relative links become
  absolute GitHub URLs. Links inside an included snippet are resolved
  against the including page and not checked by --strict, so relative
  ones rendered broken on the site; absolute ones also work on PyPI.
- A `docs` dependency group pins Zensical below 0.1: it is pre-1.0, so
  upgrades should be deliberate.
- .readthedocs.yaml and a Docs workflow run the same strict build, so a
  broken link or docstring reference fails the PR rather than the site.
- pyproject.toml gains the Documentation URL for PyPI.

Refs #81
@allen0099 allen0099 added the documentation Improvements or additions to documentation label Sep 25, 2026
Read the Docs serves the project under /en/latest/, so a root site_url
gave every page a canonical link and sitemap entry that only reach the
content through a redirect.
@allen0099
allen0099 merged commit 3779e72 into master Sep 25, 2026
10 checks passed
@allen0099
allen0099 deleted the docs/zensical-site branch September 25, 2026 08:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant