docs: publish the documentation with Zensical on Read the Docs - #82
Merged
Merged
Conversation
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
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.
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.tomlbuilds a site from the existing guides:docs/api/*.md);pymdownx.snippets, so each is written once.README.md,docs/CONTRIBUTING.mdanddocs/README.zh-TW.mdbecome 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.docsdependency group:zensical>=0.0.65,<0.1andmkdocstrings-python. Zensical is pre-1.0, so upgrades should be deliberate.uv.lockgains only these packages..readthedocs.yamland a new Docs workflow both runzensical build --strict, so a broken link or docstring reference fails the PR instead of the published site.[project.urls]gains aDocumentationentry.Notes
site_urlis fixed tohttps://fastapi-cachex.readthedocs.io/, because Zensical cannot readREADTHEDOCS_CANONICAL_URL. It must match the Read the Docs project slug.CACHE_FLOW.md,JWT_CLAIMS.mdand part ofSESSION.mdare 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 withuv sync --frozen --only-group docs --no-install-project, the same command CI and Read the Docs run.uv-lockhook was skipped, because it upgrades unrelated dependencies;uv lock --checkpasses.