documentation-writing

# FastStream Documentation Writing ## Layout - Pages: `docs/docs/en/...` (markdown, mkdocs-material). `docs/docs/en/` is the mkdocs `docs_dir`, so images live in `docs/docs/en/assets/`. - Runnable code snippets: `docs/docs_src/<topic>/...` (fully excluded from ruff — see `exclude` in `ruff.toml`). - Navigation: `docs/docs/navigation_template.txt` — new pages need an entry there. It is rendered into the gitignored `docs/docs/en/SUMMARY.md` (literate-nav). - API reference pages are generated by `docs/create_api_docs.py` — never hand-edit them. ## Code snippets Never inline non-trivial code in markdown. Put a runnable Python file in `docs/docs_src/` and embed it with `mdx_include`: ```python linenums="1" hl_lines="10" {!> docs_src/getting_started/publishing/kafka/broker.py !} ``` New `docs_src` snippets should get a test under `tests/docs/<topic>/test_<feature>.py` — one test file covers all broker variants via require marks (e.g. `@require_aiokafka`), not one file per broker subdir (see the **testing-patterns** skill). Some examples are intentionally untested; the exemptions are listed in the coverage `omit` list in `pyproject.toml`. `tests/docs/test_snippets_are_tested.py` holds the line: a `docs_src` file that no test imports (directly, or through another tested snippet) fails it unless it is in `omit`. Its `NOT_TESTED_YET` set is the backlog from before the check — take an entry out when you test it, never add one. A snippet test imports the runnable objects from the module and exercises them in-memory — never a bare `import module` (it tests nothing and trips ruff `F401`): ```python import pytest from faststream.nats import TestApp, TestNatsBroker @pytest.mark.nats() @pytest.mark.asyncio() async def test_basic() -> None: from docs.docs_src.nats.js.pull_sub import app, broker, handle async with TestNatsBroker(broker), TestApp(app): await broker.publish("Hi!", "test") handle.mock.assert_called_once_with("Hi!") ``` `just mypy` checks `docs/docs_src/` too. The annotation checks are off there (a handler may omit `-> None`, a bare `dict` is fine), every other check is on: a snippet that calls the public API wrongly fails CI. A snippet that is right while mypy disagrees points at an annotation in `faststream/` — fix it there, in its own PR with a case in `tests/mypy/`. A snippet that is wrong on purpose gets a commented per-module `[[tool.mypy.overrides]]` in `pyproject.toml`, not a `# type: ignore` the reader would see. The test imports via the `docs.docs_src.…` package path, while the markdown embeds it via the `docs_src/…` path (mdx_include `base_path` is `docs/`). Either way the snippet MUST live under `docs/docs_src/`, not repo-root `docs_src/` — otherwise the embed silently resolves to nothing and the import fails. ## Markdown conventions - External links: `[text](https://...){.external-link target="_blank"}`; internal links: `{.internal-link}`. - Multi-broker pages use pymdownx tabs with one snippet per broker: ```markdown === "AIOKafka" ...embedded kafka snippet... === "Confluent" ...embedded confluent snippet... === "RabbitMQ" ...embedded rabbit snippet... ``` - Admonitions (`!!! note`, `!!! tip`, `!!! warning`) are available and encouraged for caveats. ## Example-code rules (FastStream usage) All example code must follow idiomatic FastStream usage: - Create the broker outside the app and pass it positionally: `app = FastStream(broker)`. Don't use `app.broker`. - Prefer the `faststream.Logger` annotation in broker handlers over `print()` (some HTTP-integration examples use `print()` for brevity). - Register subscribers/publishers only via `@broker.subscriber(...)` / `@broker.publisher(...)` (or the router equivalents). - Fully annotate handler parameters; handlers return `None` unless their return value is published. - Don't add decorator options the example doesn't need. - Use `Annotated[str, Path()]` for subject path params and `Annotated[..., Context()]` for context access (built-ins: `broker`, `context`, `logger`, `message`). - Import only from public packages — never `faststream._internal`. ## Build & serve - `just docs-serve` — live dev server on port 8000. - `just docs-build` — build the static site. - `just docs-build-api` — regenerate the API reference. - `just docs-check` — the PR gate: strict build of the guides (broken links and anchors fail) plus `docs/check_site.py` (unique titles, canonicals, sitemap, JSON-LD, image `alt`), about 10 s. Run it before pushing a docs change. ## Related skills - **testing-patterns** — how to mark and run the snippet tests in `tests/docs/`. - **code-architecture** — source conventions example code must follow (public API only, no `_internal` imports). - **dev-workflow** — environment setup for the docs toolchain.