feat(template): replace MkDocs with Sphinx + Shibuya docs - #42
Merged
Conversation
Migrate generated-project documentation from MkDocs/mkdocs-material to Sphinx with the bare Shibuya theme, reStructuredText, and an autodoc API reference (autodoc + napoleon). Replaces mkdocs.yml + the four Markdown pages with docs/conf.py and .rst pages; switches the tox docs envs and both CI workflows from `mkdocs gh-deploy` to `sphinx-build` + `ghp-import` (unchanged gh-pages-branch model). Drops the now-unneeded check-yaml `--unsafe` flag and pins the docs dependency group exactly. See ADR-006.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Sorry @hasansezertasan, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6d41ed4d7a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The MkDocs->Sphinx migration shipped a docs setup that failed for freshly generated projects on the supported Python floor: - sphinx-autobuild 2025.8.25 and sphinx-design 0.7.0 require Python >=3.11, making uv's universal lock unsatisfiable for the 3.10 split (requires-python is >=3.10). Pin to the last 3.10-compatible releases (2024.10.3 / 0.6.1). - conf.py shipped multi-line `source_suffix`/`intersphinx_mapping` literals that violate `skip-magic-trailing-comma`, so the prek `ruff-format` CI hook would fail. Single-line the literals; add the conditional pydantic mapping via assignment. Also tightens the new Sphinx config: - Configure auto_pytabs_min/max_version to (3,10)/(3,14) so version tabs match the project's supported range instead of auto-pytabs' (3,7) default. - Add pydantic intersphinx for web variants (FastAPI/Litestar use pydantic), not just pydantic-settings/worker. - Derive the copyright year at build time instead of hardcoding 2025. Verified across empty/FastAPI/Litestar variants: uv lock resolves on 3.10-3.14, `sphinx-build -W` builds cleanly, and the full tox `style` env passes.
The "Modules" heading in docs/modules.rst is exactly 7 characters, so its RST underline rendered as `=======` — a 7-char `=` line that `git diff --check` (and pre-commit's check-merge-conflict) treats as a leftover merge-conflict separator. Lengthen the underline past 7 characters and document why, so the generated docs/modules.rst is no longer flagged as containing a conflict marker.
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
1 participant
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.
Summary
Migrates generated-project documentation from MkDocs (
mkdocs+mkdocs-material) to Sphinx with the bare Shibuya theme — the same stack behind the Litestar-org docs sites (Litestar, Advanced Alchemy, Polyfactory). Motivated by MkDocs 2.0 instability and by the fact that the old setup shippedmkdocs-materialwithout ever activating it and hand-maintained the "API reference."Decisions (see ADR-006): bare Shibuya (PyPI, no Litestar branding) over
litestar-sphinx-theme(git dep) · reStructuredText · autodoc + napoleon for a real API reference. Docs remain unconditional (noinclude_docstoggle).Changes
docs/conf.py.jinja(Shibuya theme; autodoc, napoleon, intersphinx, sphinx-design/copybutton/togglebutton/paramlinks, auto-pytabs, myst-parser, andsphinx-clickonly wheninclude_cli) anddocs/{index,installation,usage,modules}.rst.jinja.modules.rstis conditional.. automodule::directives.mkdocs.yml.jinjaand the four*.md.jinjapages.docsdependency group; toxdocs-build/docs-servernow runsphinx-build/sphinx-autobuildwithextras = ["all"](autodoc must import the package + optional deps); keywordmkdocs→sphinx;docs/conf.pyadded to ruffINP001ignores.sphinx-buildand publish withghp-import— the same tool MkDocs used under the hood, so the gh-pages-branch model and Pages settings are unchanged.check-yaml --unsafe(only needed formkdocs.yml's!!python/nametags); removed a redundant docstringAttributes:block inlogging_setup.pythat caused a duplicate-autodoc warning; updated README/AGENTS/CLAUDE/ADR-002 references.Verification
docs-buildsucceeds with zero warnings across empty, FastAPI, and Litestar variants (conditional autodoc,sphinx-click, and pydantic intersphinx all resolve).tox rungreen across Python 3.10–3.14 (21 tests) plus the completestyleenv (ruff, mypy, basedpyright, ty, pyrefly, zuban, vulture, slotscheck, taplo, validate-pyproject, typos, actionlint).Notes
copier update.Follow-up fixes (review)
Verification on freshly generated projects surfaced issues the original commit's checks masked (tox runs
ruff formatwithout--check, so it auto-fixed locally;uv lockresolution wasn't re-run against the 3.10 floor). Fixed in a follow-up commit:sphinx-autobuild(2025.8.25) andsphinx-design(0.7.0) require Python ≥3.11, making thedocsgroup unsatisfiable on the 3.10 split of uv's universal lock. Pinned to the last 3.10-compatible releases —sphinx-autobuild==2024.10.3andsphinx-design==0.6.1. (These intentionally trail latest; do not let Renovate bump them past the 3.11 cutoff while 3.10 is supported.)ruff-format(prek hooks job):conf.pyshipped multi-linesource_suffix/intersphinx_mappingliterals that violateskip-magic-trailing-comma. Single-lined them; conditional pydantic mapping now added via assignment.auto_pytabs_min_version=(3,10)/max_version=(3,14)(defaults are(3,7)).2025.Re-verified across empty/FastAPI/Litestar:
uv lockresolves on 3.10–3.14,sphinx-build -Wbuilds cleanly, and the full toxstyleenv passes (all 15 checks).