Sdk Reference Docs

📝 SELF-UPDATING DOCUMENT: Verify against the actual codebase and update this file when it drifts.

Overview

The SDK reference sections under frontend/docs/content/docs/reference/{python,typescript,go,ruby} are generated from SDK source — doc comments and docstrings are the source of truth. Never hand-edit generated .mdx; the next regeneration overwrites it. To change reference content, edit the doc comment/docstring in the SDK and regenerate.

Commands

task generate-sdk-docs             # all four languages (also part of `task generate`)
task generate-sdk-docs-python      # sdks/python/docs/generate.sh
task generate-sdk-docs-typescript  # sdks/typescript/docs/generate.sh
task generate-sdk-docs-go          # (cd sdks/go && go run ./docs/generator)
task generate-sdk-docs-ruby        # sdks/ruby/docs/generate.sh

All four pipelines are fully deterministic; no AI/LLM is involved anywhere and no API keys are needed.

CI: .github/workflows/gen-sdk-docs.yml runs on pushes to main touching sdks/** or pkg/worker/** (the Go generator also reads pkg/worker for the Context interfaces). It detects which SDKs changed, regenerates only those, opens a PR labeled autogenerated-sdk-docs, and requests auto-squash-merge. workflow_dispatch only runs from main. Optional SDK_DOCS_PR_TOKEN secret (PAT/App token) makes generated PRs trigger normal CI.

Per-language pipelines

Ownership rules

• Generators own: every .mdx in their section + feature-clients/meta.json.
• Section meta.json (e.g. python/meta.json) is merged, not overwritten: existing order and separator strings (e.g. ---Python Specifics---) are preserved; new pages auto-append; dead entries are removed.
• Hand-authored pages exist only in Python (asyncio, pydantic, lifespans, dependency-injection, dataclasses) — generators never touch them.
• reference/meta.json (top-level) is hand-maintained. Nothing generates it. So is reference/index.mdx.
• Generators hard-fail if an emitted page is unreachable from a meta.json.
• Each generator also emits <lang>/index.mdx (the section overview) from the shared hand-maintained mapping frontend/docs/reference-map.json, which pairs each canonical feature-client concept with per-language page slugs and its user-guide page. Generators hard-fail on an emitted feature-client page with no mapping entry, a mapping slug matching no emitted page, or a guide path that does not exist. Adding a feature client to any SDK therefore requires adding (or extending) its reference-map.json entry.

Gotchas (learned the hard way)

1. fumadocs dropdown: a root: true folder only appears in the section dropdown if it has an index page or a direct page child. The Reference folder now has a hand-maintained index.mdx, and app/(docs)/layout.tsx still adds a fallback tab bound with $folder (for active-state detection), deduped by URL, pointing at /reference. The per-language sections also have generated index pages, so /reference/<lang> serves an overview rather than redirecting to the client page.
2. Never put {/* */} JSX comments in this repo's MDX — the prettier pass rewrites * to _ inside them, producing invalid MDX that 500s the whole docs site.
3. Determinism is a requirement: every generator must produce byte-identical output across runs (sorted iteration everywhere), or CI churns endless PRs. Verify with a double run + checksum diff. Output must not depend on optional tooling: the Go generator hard-fails if frontend/docs prettier is missing (a silent skip once shipped unformatted pages via CI while local runs looked clean).
4. golangci-lint: repo uses v2 config; os.WriteFile in generators must use 0o600.
5. Don't edit frontend/docs/pages/** — that's the dead pre-fumadocs tree.
6. No em dashes in docs content (.cursor/rules/docs-writing-style.mdc): use commas, parentheses, or separate sentences. Generated pages inherit them from SDK doc comments, so fix them at the source.

Adding a new SDK language

1. Build a generator under sdks/<lang>/docs/ with a generate.sh entry point (or go run ./docs/generator style) that emits the standard layout: client.mdx, context.mdx, runnables.mdx, feature-clients/*.mdx + feature-clients/meta.json, into frontend/docs/content/docs/reference/<lang>/. Use content/docs/reference/python/ as the style template. Auto-discover feature clients from source; no hand-lists.
2. Hand-write the initial <lang>/meta.json (client, context, feature-clients, runnables); the generator merges it afterward.
3. Add a generate-sdk-docs-<lang> task to the root Taskfile and wire it into generate-sdk-docs.
4. Add the language to .github/workflows/gen-sdk-docs.yml: the for lang in ... loop in the detect step, a toolchain setup step if needed, and a conditional generate step.
5. Add "<lang>" to frontend/docs/content/docs/reference/meta.json.