docs: add bilingual mkdocs-material site with API reference and Pages deploy

Material for MkDocs, English (default) + Russian via mkdocs-static-i18n, an
mkdocstrings API reference from the Google docstrings, a Swagger-UI
illustration and runnable examples throughout. Split into a concise Overview
and a detailed Guide. GitHub Actions builds and deploys to Pages.

Author: feodor-ra

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - pyproject.toml
+      - uv.lock
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --no-dev --group docs
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -12,3 +12,7 @@ wheels/
 # Test artifacts
 .coverage
 .pytest_cache/
+
+# Docs build
+site/
+.cache/

CLAUDE.md

@@ -92,6 +92,7 @@ src-layout, package `src/fastapi_typed_errors/`:
 - Registration-only stub endpoints in tests end with `raise NotImplementedError` (ty `all = "error"` rejects `...` bodies with non-`None` return annotations outside stubs/protocols).
 - Test structure: **AAA** (Arrange / Act / Assert), the blocks separated by blank lines; single-expression tests may collapse to one line (e.g. `assert error_models(X) is X.model`). Every test opens with a short one-line docstring describing the case; test functions are annotated `-> None`.
 - Prefer pytest **fixtures** for reusable arrange values (request objects, configured apps, built artifacts) — typed, with a docstring and a `Returns:` section. Module level is only for error classes/enums that must exist at import time (they are used in type positions). Don't name a fixture `request` — it clashes with pytest's built-in.
-- Lint everything: `just lint` (ruff format --check, ruff check, ty check). Run `uv run ruff format` to apply formatting.
+- Lint everything: `just lint` (ruff format --check, ruff check, ty check). Run `uv run ruff format` to apply formatting. **ruff (preview) also formats Python code blocks inside Markdown** (`README.md`, `docs/**`), so keep doc snippets canonically formatted and re-run `just lint` after editing prose with code.
+- Docs: **Material for MkDocs**, bilingual (EN default at `/`, RU at `/ru/`) via `mkdocs-static-i18n` (folder mode: `docs/en/**`, `docs/ru/**`; `nav_translations` localize the nav; language-specific assets like the Swagger SVG live per-language, shared CSS in `docs/stylesheets/`). API reference is auto-generated from Google docstrings via `mkdocstrings[python]` (`:::` blocks). Deps in the `docs` group (`~=`); serve `just docs`, strict build `just docs-build`. Published to GitHub Pages by `.github/workflows/docs.yml` (uv build + `upload-pages-artifact`/`deploy-pages`; Pages source = "GitHub Actions").
 - Environment and build: uv (`uv sync`, `uv run python ...`), build backend `uv_build`.
 - Run smoke checks against a live FastAPI app: `uv run python <script>` (`httpx2` for `TestClient` is in the dev group, so no `--with` is needed anymore).

Justfile

@@ -11,3 +11,11 @@ lint:
 # Run the test suite with coverage.
 test:
     uv run pytest --cov
+
+# Serve the documentation site locally with live reload.
+docs:
+    uv run --group docs mkdocs serve
+
+# Build the documentation site in strict mode.
+docs-build:
+    uv run --group docs mkdocs build --strict

README.md

@@ -81,7 +81,7 @@ router = with_errors(APIRouter(), auto=True)
 def get_item(item_id: int, user: Annotated[User, Depends(current_user)]) -> Item:
     if item_id == 0:
         raise NotFoundError(f"No item {item_id}")  # auto -> 404
-    return Item(item_id=item_id)                    # + whatever current_user can raise
+    return Item(item_id=item_id)  # + whatever current_user can raise
 ```
 
 ## Core layer only

docs/en/assets/swagger-responses.svg

@@ -0,0 +1,111 @@
+---
+title: CI checker
+---
+
+# CI checker: check_raises
+
+`Raises[...]` annotations are a declaration. `check_raises` statically verifies that the declaration **matches** what a route can actually raise — in the endpoint itself, its helpers and its whole dependency tree. This closes the gap that annotations leave open: a forgotten declaration, or a dead one you no longer raise.
+
+## Library usage
+
+It fits perfectly into a test:
+
+```python
+from fastapi_typed_errors import check_raises
+
+
+def test_error_contracts() -> None:
+    report = check_raises(app)  # a FastAPI app or an APIRouter
+    assert report.ok, report.routes
+```
+
+`check_raises` returns a [`RaisesReport`](../reference/analysis.md) with an `.ok` property and a list of discrepancies `.routes`.
+
+## Two discrepancy categories
+
+Each `RouteDiscrepancy` holds two **independent** buckets:
+
+| Category | What it means | Default |
+|---|---|---|
+| `undeclared` | raised in code but absent from `Raises` | **always a failure** |
+| `overdeclared` | declared but its raise is not found | a failure (toggleable) |
+
+```python
+report = check_raises(app)
+for route in report.routes:
+    print(route.path, route.methods)
+    print("  undeclared:", [e.__name__ for e in route.undeclared])
+    print("  overdeclared:", [e.__name__ for e in route.overdeclared])
+```
+
+Since AST analysis is conservative (it may not see dynamic `raise`s), `overdeclared` sometimes gives a false positive. In that case turn that bucket off:
+
+```python
+report = check_raises(app, allow_overdeclared=True)  # ignore extra declarations
+```
+
+!!! tip "Keep overdeclared on if you can"
+
+    It catches dead declarations that pile up in OpenAPI. Reach for `allow_overdeclared=True` only for code with dynamic `raise`s the walker can't see.
+
+## CLI
+
+The same check as a command — handy in a CI pipeline. It needs the `cli` extra:
+
+```bash
+pip install "fastapi-typed-errors[cli]"
+```
+
+You point it at an app path in `module:attribute` form:
+
+```bash
+fastapi-typed-errors check app.main:app
+```
+
+=== "Match (exit 0)"
+
+    ```console
+    $ fastapi-typed-errors check app.main:app
+    All 12 route(s) match their Raises declarations.
+    ```
+
+=== "Discrepancies (exit 1)"
+
+    ```console
+    $ fastapi-typed-errors check app.main:app
+    ┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+    ┃ Route           ┃ Undeclared     ┃ Overdeclared  ┃
+    ┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+    │ GET /items      │ ForbiddenError │ -             │
+    └─────────────────┴────────────────┴───────────────┘
+    1 of 12 route(s) have discrepancies.
+    ```
+
+Flags: `--allow-overdeclared`, `--max-depth N`.
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | all declarations match |
+| `1` | discrepancies found (a table) |
+| `2` | a usage/loading error (bad path, not an app, unresolvable `Raises`) |
+
+## What exactly is compared
+
+- **Declared** — the union of `Raises[...]` markers from the endpoint's return annotation. It is read straight from the annotations, so it works **regardless** of whether the router was wrapped with `with_errors`.
+- **Raised** — `raise` statements from the endpoint's source **plus** every node of the `Depends` tree (security schemes are skipped).
+
+The walker understands the `get_or_404(error=NotFoundError)` factory pattern (the error class arrives as a call argument), closures, cross-module helpers and `functools.partial`. It runs in one process and **never executes** your code. For the false negatives (local variables, `self.method()` chains, dynamics) see [Limitations](limitations.md#walker).
+
+!!! example "GitHub Actions"
+
+    ```yaml
+    - run: uv run fastapi-typed-errors check app.main:app
+    ```
+
+    Or run it via a test — `assert check_raises(app).ok` — and you won't need the separate CLI dependency.
+
+---
+
+**Next:** [Customization](customization.md) — your own response model, codes, `ABC` compatibility.