/litestar-docs

name: litestar-docs
description: "Use when working with zensical.toml, docs/conf.py, sphinx, shibuya, litestar-sphinx-theme, mkdocstrings, Griffe, objects.inv, or API reference docs. Not for OpenAPI route schemas."

litestar-docs

Dual-engine documentation architecture for `litestar-org` and ecosystem repositories, supporting both **Sphinx** (`docs/conf.py` + `shibuya` / `litestar-sphinx-theme` + `autodoc` / `napoleon`) and **Zensical** (`zensical.toml` + `mkdocstrings-python` / Griffe static AST). Match the repository's chosen documentation engine and apply shared quality invariants across both.

Documentation Engine Matrix

| Aspect | Sphinx (`docs/conf.py`) | Zensical (`zensical.toml`) | | --- | --- | --- | | **Primary Config** | `docs/conf.py` | `zensical.toml` | | **Markup Formats** | `.rst` (reStructuredText) + `.md` (`myst-parser`) | `.md` (Python Markdown + `pymdown-extensions`) | | **Theme & Styling** | `shibuya` or `litestar-sphinx-theme` (`docs/_static/custom.css`) | `variant = "modern"` (`docs/stylesheets/extra.css`) | | **Python API Extraction** | `sphinx.ext.autodoc` + `sphinx.ext.napoleon` | `mkdocstrings-python` (Griffe static AST) | | **Cross-Repo Linking** | `sphinx.ext.intersphinx` (`objects.inv`) | `mkdocstrings` (`enable_inventory = true`, `objects.inv`) | | **UI Components & Tabs** | `sphinx-design` (`.. grid::`, `.. tab-set::`), `auto-pytabs` | `pymdownx.tabbed` (`content.tabs.link`), `pymdownx.details` | | **Code Inclusion** | `.. literalinclude::` | `pymdownx.snippets` (`--8<--`, `check_paths = true`) | | **CLI Reference** | `sphinx-click` (`.. click::`) | `tools/docs/generate_cli_docs.py` | | **Diagrams** | `sphinxcontrib-mermaid` (`.. mermaid::`) | `pymdownx.superfences` (```` ```mermaid ````) |

Core Rules

• **Match the repository's existing documentation engine.** Reason: Both Sphinx and Zensical are first-class engines in the Litestar ecosystem; inspect `docs/conf.py` vs `zensical.toml` before making edits.
• **Enforce a `68–75ch` (`46rem`) reading column with persistent left and right sidebars.** Reason: Uncapped prose columns and hidden right-hand `"On this page"` outlines degrade scannability on technical pages.
• **Cap guide pages at `<= 12` viewports (`~80–200` lines) and Reference pages at `<= 120 KB` HTML (`<= 14` TOC items).** Reason: Monolithic module dumps with 15+ classes and 200+ inherited methods bury primary constructors.
• **Disable inherited members on leaf classes and show base classes (`show_bases = true` / `:show-inheritance:`).** Reason: Base driver or repository methods belong once on the base class Reference page.
• **Document every public `TypedDict` and `msgspec.Struct` field with a PEP 257 inline docstring immediately below the field.** Reason: Sphinx `autoclass` renders zero fields without inline attribute docstrings, and Griffe requires them to build structured parameter tables.
• **Never write docstrings on `@overload` stubs or leak internal compiler notes (`mypyc`, `PyCapsule`) into public docstrings.** Reason: Both engines render overload docstrings ahead of the implementation docstring.
• **Execute standalone `docs/examples/**/*.py` modules in `pytest`.** Reason: Standalone modules checked by `ruff`, `pyright`, and `pytest` stay runnable and prevent snippet rot.
• **Use `[data-md-color-scheme]` CSS classes (not `<picture><source media="(prefers-color-scheme: dark)">`) for light/dark hero banners on Zensical pages, hide single-page left sidebars on `Home`, and omit redundant `<h1>` titles above hero logos.** Reason: `<picture>` media queries only respond to OS-level dark mode and fail when toggling Zensical's theme button (`[data-md-color-scheme="slate"]`).
• **Keep headings unnumbered and free of inline `` `code` `` pills, reserve bordered code pills strictly for clickable links (`a > code`), keep tab labels short (`white-space: nowrap`), and never write `\|` inside backticked code in Markdown tables.** Reason: Python-Markdown splits table cells on `|` before backticks are parsed (leaving literal `\|` in `<code>`), and bordered pills on every non-link code span create visual noise.

Quick Reference

| Topic | Reference File | Key Contents | | --- | --- | --- | | Sphinx Architecture | [`references/sphinx-architecture.md`](references/sphinx-architecture.md) | `docs/conf.py`, `shibuya` / `litestar-sphinx-theme`, `autodoc` + `napoleon`, `sphinx-design`, `custom.css` | | Zensical Architecture | [`references/zensical-architecture.md`](references/zensical-architecture.md) | `zensical.toml`, built-in plugins, `mkdocstrings-python`, `pymdownx`, `postbuild.py`, `verify_docs_artifacts.py` | | Information Architecture | [`references/information-architecture.md`](references/information-architecture.md) | Domain tabs (`Learn`, `Databases`, `Integrations`, `Reference`), page budgets, WCAG AAA palette, tutorial structure | | Python Docstrings | [`references/python-docstrings.md`](references/python-docstrings.md) | Google style, inline `TypedDict` / `msgspec.Struct` docstrings, type alias leak prevention, AST scanner | | Database Adapter Docs | [`references/database-adapters.md`](references/database-adapters.md) | Central Capability Matrix, 1-page per-driver guide, own-symbols-only Reference templates (Sphinx & Zensical) | | Polyglot & CLI Docs | [`references/polyglot-cli.md`](references/polyglot-cli.md) | TypeScript (`TypeDoc` / `mkdocstrings-typescript`), Rust (`.pyi` stubs + `/rustdoc/`), Click CLI generation | | Interop & Redirects | [`references/migration-interop.md`](references/migration-interop.md) | Directive translation matrix, cross-engine `objects.inv` linking, URL redirect stubs |

<workflow>

Workflow

Step 1: Detect Engine and Configure Dependencies

Inspect the repository root for `docs/conf.py` (Sphinx) or `zensical.toml` (Zensical):

• **Sphinx Track**: Configure `[dependency-groups] doc` with `sphinx`, `shibuya` (or `litestar-sphinx-theme`), `sphinx-design`, `sphinx-copybutton`, `sphinx-click`, `sphi