docs(api): generate typed language references with rendered docstrings

.github/actions/changed-files/action.yml

@@ -7,6 +7,9 @@ inputs:
     required: true
 
 outputs:
+  api_docs:
+    description: 'Whether generated API documentation inputs changed'
+    value: ${{ steps.filter.outputs.api_docs_any_modified }}
   core:
     description: 'Whether core files changed'
     value: ${{ steps.filter.outputs.core_any_modified }}
@@ -141,6 +144,7 @@ runs:
         echo "changed_keys: ${{ steps.filter.outputs.changed_keys }}"
         echo ""
         echo "=== Filter Results ==="
+        echo "api_docs: ${{ steps.filter.outputs.api_docs_any_modified }}"
         echo "docs: ${{ steps.filter.outputs.docs_any_modified }}"
         echo "ci: ${{ steps.filter.outputs.ci_any_modified }}"
         echo "core: ${{ steps.filter.outputs.core_any_modified }}"
@@ -163,6 +167,7 @@ runs:
         echo "rust: ${{ steps.filter.outputs.rust_any_modified }}"
         echo ""
         echo "=== Files Matching Each Filter ==="
+        echo "api_docs: ${{ steps.filter.outputs.api_docs_all_modified_files }}"
         echo "docs: ${{ steps.filter.outputs.docs_all_modified_files }}"
         echo "ci: ${{ steps.filter.outputs.ci_all_modified_files }}"
         echo "core: ${{ steps.filter.outputs.core_all_modified_files }}"
@@ -188,7 +193,7 @@ runs:
       shell: bash
       run: |
         # Combine all filter-specific files into one list
-        COVERED_FILES=$(echo "${{ steps.filter.outputs.docs_all_modified_files }} ${{ steps.filter.outputs.examples_all_modified_files }} ${{ steps.filter.outputs.ignore_all_modified_files }} ${{ steps.filter.outputs.ci_all_modified_files }} ${{ steps.filter.outputs.core_all_modified_files }} ${{ steps.filter.outputs.operator_all_modified_files }} ${{ steps.filter.outputs.snapshot_all_modified_files }} ${{ steps.filter.outputs.snapshot_vllm_all_modified_files }} ${{ steps.filter.outputs.snapshot_sglang_all_modified_files }} ${{ steps.filter.outputs.snapshot_trtllm_all_modified_files }} ${{ steps.filter.outputs.power_agent_all_modified_files }} ${{ steps.filter.outputs.deploy_all_modified_files }} ${{ steps.filter.outputs.planner_all_modified_files }} ${{ steps.filter.outputs.sidecar_all_modified_files }} ${{ steps.filter.outputs.vllm_all_modified_files }} ${{ steps.filter.outputs.sglang_all_modified_files }} ${{ steps.filter.outputs.trtllm_all_modified_files }} ${{ steps.filter.outputs.sample_all_modified_files }} ${{ steps.filter.outputs.frontend_all_modified_files }} ${{ steps.filter.outputs.benchmarks_all_modified_files }} ${{ steps.filter.outputs.efa_all_modified_files }} ${{ steps.filter.outputs.rust_all_modified_files }}" | tr ' ' '\n' | grep -v '^$' | sort -u)
+        COVERED_FILES=$(echo "${{ steps.filter.outputs.api_docs_all_modified_files }} ${{ steps.filter.outputs.docs_all_modified_files }} ${{ steps.filter.outputs.examples_all_modified_files }} ${{ steps.filter.outputs.ignore_all_modified_files }} ${{ steps.filter.outputs.ci_all_modified_files }} ${{ steps.filter.outputs.core_all_modified_files }} ${{ steps.filter.outputs.operator_all_modified_files }} ${{ steps.filter.outputs.snapshot_all_modified_files }} ${{ steps.filter.outputs.snapshot_vllm_all_modified_files }} ${{ steps.filter.outputs.snapshot_sglang_all_modified_files }} ${{ steps.filter.outputs.snapshot_trtllm_all_modified_files }} ${{ steps.filter.outputs.power_agent_all_modified_files }} ${{ steps.filter.outputs.deploy_all_modified_files }} ${{ steps.filter.outputs.planner_all_modified_files }} ${{ steps.filter.outputs.sidecar_all_modified_files }} ${{ steps.filter.outputs.vllm_all_modified_files }} ${{ steps.filter.outputs.sglang_all_modified_files }} ${{ steps.filter.outputs.trtllm_all_modified_files }} ${{ steps.filter.outputs.sample_all_modified_files }} ${{ steps.filter.outputs.frontend_all_modified_files }} ${{ steps.filter.outputs.benchmarks_all_modified_files }} ${{ steps.filter.outputs.efa_all_modified_files }} ${{ steps.filter.outputs.rust_all_modified_files }}" | tr ' ' '\n' | grep -v '^$' | sort -u)
 
         # Get all modified files
         ALL_FILES=$(echo "${{ steps.filter.outputs.all_all_modified_files }}" | tr ' ' '\n' | grep -v '^$' | sort -u)

.github/filters.yaml

@@ -42,6 +42,23 @@ docs:
   # Sidecar documentation is not part of the Fern docs site.
   - '!lib/sidecar/**'
 
+api_docs:
+  - '.github/filters.yaml'
+  - '.github/workflows/fern-docs.yml'
+  - '.github/workflows/pre-merge.yml'
+  - 'pyproject.toml'
+  - 'docs/fern/scripts/**'
+  - 'docs/fern/components/**'
+  - 'docs/fern/pages/reference/api/**'
+  - 'docs/fern/index.yml'
+  - 'docs/fern/docs.yml'
+  - 'docs/fern/pages/reference/kubernetes-api/full-api-reference.mdx'
+  - 'docs/fern/pages/reference/kubernetes-api/additional-resources/api-reference-k8s.md'
+  - 'deploy/operator/docs/footer.md'
+  - 'lib/bindings/python/src/**'
+  - 'components/src/dynamo/**'
+  - '**/Cargo.toml'
+
 examples:
   - 'recipes/**'
   - 'examples/**'

.github/workflows/fern-docs.yml

@@ -118,6 +118,18 @@ jobs:
           path: source-checkout
           fetch-depth: 1
 
+      - name: Setup Python for API reference generation
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: '3.13'
+
+      - name: Check generated API references
+        run: |
+          python3 -m pip install 'griffe==2.1.0'
+          python3 source-checkout/docs/fern/scripts/gen_python_api.py --check
+          python3 source-checkout/docs/fern/scripts/gen_rust_api.py --check
+          python3 source-checkout/docs/fern/scripts/gen_kubernetes_api.py --check
+
       - name: Checkout docs-website branch
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:

.github/workflows/pre-merge.yml

@@ -32,6 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       docs: ${{ steps.changes.outputs.docs }}
+      api_docs: ${{ steps.changes.outputs.api_docs }}
       operator: ${{ steps.changes.outputs.operator }}
       snapshot: ${{ steps.changes.outputs.snapshot }}
       rust: ${{ steps.changes.outputs.rust }}
@@ -47,7 +48,7 @@ jobs:
 
   pre-merge-status-check:
     runs-on: ubuntu-latest
-    needs: [changed-files, pre-commit, fern-check, docs-website-composition, fern-broken-links, operator, snapshot, rust-tests, rust-clippy]
+    needs: [changed-files, pre-commit, api-docs, fern-check, fern-broken-links, operator, snapshot, rust-tests, rust-clippy, docs-website-composition]
     if: always()
     steps:
       - name: "Check all dependent jobs"
@@ -64,6 +65,46 @@ jobs:
     - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
       timeout-minutes: 3
 
+  api-docs:
+    name: Generated API References
+    needs: changed-files
+    if: needs.changed-files.outputs.api_docs == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+      with:
+        python-version: '3.13'
+    - name: Install API docs test dependencies
+      # pydantic and pytest-benchmark satisfy the module-referencing
+      # filterwarnings entries in the repository's pyproject.toml so pytest
+      # can load them under the repository's shared config.
+      run: |
+        python3 -m pip install \
+          'griffe==2.1.0' \
+          'pytest>=8.0' \
+          'pyyaml>=6.0' \
+          'pydantic>=2' \
+          'pytest-asyncio>=1.0' \
+          'pytest-benchmark>=4'
+    - name: Test generated API references
+      # docs/fern/scripts/tests is an explicit path so it opts back into
+      # collection despite the pyproject's docs/* ignore-glob (which keeps
+      # the rendered docs site content out of the default suite).
+      run: |
+        python3 -m pytest -q \
+          docs/fern/scripts/tests/test_gen_python_api.py \
+          docs/fern/scripts/tests/test_gen_rust_api.py \
+          docs/fern/scripts/tests/test_gen_kubernetes_api.py \
+          docs/fern/scripts/tests/test_api_reference_regressions.py
+    - name: Check generated API reference freshness
+      run: |
+        python3 docs/fern/scripts/gen_python_api.py --check
+        python3 docs/fern/scripts/gen_rust_api.py --check
+        python3 docs/fern/scripts/gen_kubernetes_api.py --check
+
   # Safe Fern docs checks run in pre-merge with read-only permissions.
   fern-check:
     name: Fern Configuration Check

deploy/operator/docs/footer.md

@@ -131,9 +131,8 @@ Worker components receive the following probe configurations:
 - **Timeout**: 5 seconds
 - **Failure Threshold**: 720 (allows up to 2 hours for startup: 10s × 720 = 7200s)
 
-:::{note}
-For larger models (typically >70B parameters) or slower storage systems, you may need to increase the `failureThreshold` to allow more time for model loading. Calculate the required threshold based on your expected startup time: `failureThreshold = (expected_startup_seconds / period)`. Override the startup probe in your component specification if the default 2-hour window is insufficient.
-:::
+> [!NOTE]
+> For larger models (typically >70B parameters) or slower storage systems, you may need to increase the `failureThreshold` to allow more time for model loading. Calculate the required threshold based on your expected startup time: `failureThreshold = (expected_startup_seconds / period)`. Override the startup probe in your component specification if the default 2-hour window is insufficient.
 
 ### Multinode Deployment Probe Modifications
 

docs/fern/components/ReferenceStyles.tsx

@@ -174,6 +174,53 @@ const REFERENCE_CSS = `
     font-weight: 600;
 }
 
+/* Shared surface tone for nested content blocks (import blocks, package
+   groups, monospace signatures) — one dark/light pair so every reference
+   component reads as one system. */
+:root {
+    --dynref-nested-bg: rgba(120, 120, 120, 0.06);
+    --dynref-nested-border: var(--border, var(--grayscale-a5));
+}
+
+.dark {
+    --dynref-nested-bg: #161616;
+    --dynref-nested-border: #2b2b2b;
+}
+
+/* Shared "index page title" for the reference landing components. 20px keeps
+   the compact-index visual density. */
+.dynref-index-header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-end;
+    justify-content: space-between;
+    gap: 8px 16px;
+    margin-bottom: 12px;
+}
+
+.dynref-index-title {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 10px;
+    margin: 0;
+    color: var(--pst-color-text-base);
+    font-size: 20px;
+    font-weight: 600;
+    line-height: 1.2;
+}
+
+.dynref-index-meta {
+    margin: 0;
+    color: var(--pst-color-text-muted);
+    font-size: 12.5px;
+}
+
+.dynref-index-meta a {
+    color: inherit;
+    text-decoration: underline;
+}
+
 /* Category chips — palette replicated from main.css .dynamo-chip-*. */
 .dynref-chip {
     display: inline-flex;

docs/fern/components/releases.data.ts

@@ -722,8 +722,9 @@ export const ARTIFACTS: Artifact[] = [
     name: "dynamo-config",
     description: "Configuration management",
     meta: "MSRV Rust v1.82",
-    href: "https://crates.io/crates/dynamo-config/1.3.0",
-    tags: [{ label: "cargo add dynamo-config@1.3.0", clipboard: "cargo add dynamo-config@1.3.0" }],
+    // Not republished for 1.3.0; crates.io tops out at 1.2.1.
+    href: "https://crates.io/crates/dynamo-config/1.2.1",
+    tags: [{ label: "cargo add dynamo-config@1.2.1", clipboard: "cargo add dynamo-config@1.2.1" }],
   },
   {
     category: "crate",

docs/fern/index.yml

@@ -927,6 +927,61 @@ navigation:
 
   - tab: reference
     layout:
+      # ==================== API Reference ====================
+      # docs/fern/scripts/gen_python_api.py generates the Python landing page
+      # (Overview) and one deterministic MDX per curated module. Each
+      # per-module page is a visible sibling of the Python landing so the
+      # sidebar exposes every published module. Sections here set
+      # 'collapsed: false': Fern collapses by default, which hid the whole
+      # published surface behind a click on the tab readers open specifically
+      # to look a symbol up.
+      - section: API Reference
+        slug: api
+        collapsed: false
+        contents:
+          - page: Overview
+            path: pages/reference/api/README.mdx
+          - section: Python API
+            path: pages/reference/api/python/README.mdx
+            slug: python
+            collapsed: false
+            contents:
+              - page: dynamo._core
+                path: pages/reference/api/python/_core.mdx
+                slug: _core
+              - page: dynamo.runtime
+                path: pages/reference/api/python/runtime.mdx
+                slug: runtime
+              - page: dynamo.llm
+                path: pages/reference/api/python/llm.mdx
+                slug: llm
+              - page: dynamo.frontend
+                path: pages/reference/api/python/frontend.mdx
+                slug: frontend
+              - page: dynamo.common
+                path: pages/reference/api/python/common.mdx
+                slug: common
+              - page: dynamo.health_check
+                path: pages/reference/api/python/health_check.mdx
+                slug: health_check
+              - page: dynamo.logits_processing
+                path: pages/reference/api/python/logits_processing.mdx
+                slug: logits_processing
+              - page: dynamo.planner
+                path: pages/reference/api/python/planner.mdx
+                slug: planner
+              - page: dynamo.router
+                path: pages/reference/api/python/router.mdx
+                slug: router
+              - page: dynamo.mocker
+                path: pages/reference/api/python/mocker.mdx
+                slug: mocker
+              - page: dynamo.nixl_connect
+                path: pages/reference/api/python/nixl_connect.mdx
+                slug: nixl_connect
+          - page: Rust API
+            path: pages/reference/api/rust/README.mdx
+            slug: rust
       - page: Compatibility
         path: pages/reference/general/compatibility.mdx
       - page: Examples

docs/fern/pages/reference/api/README.mdx

@@ -0,0 +1,60 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: API Reference
+subtitle: Language-by-language public surface for Dynamo, discovered from the source tree
+---
+
+<CardGroup cols={3}>
+<Card title="Python" href="python/README.mdx">Worker decorators, HTTP frontend, planner / router / mocker configuration, and the Rust-backed runtime bindings.</Card>
+<Card title="Rust" href="rust/README.mdx">Distributed runtime crates published on crates.io, pinned to the current release.</Card>
+<Card title="Kubernetes" href="../kubernetes-api/full-api-reference.mdx">DynamoGraphDeployment, DynamoGraphDeploymentRequest, and DynamoComponentDeployment custom-resource fields.</Card>
+</CardGroup>
+
+The API Reference is a machine-generated view of Dynamo's public surface, kept
+honest by static analysis of the source tree. Each module page lists every
+class and function, expands into per-symbol signatures and public methods,
+and deep-links to the exact file and line on `main`.
+
+## Coverage
+
+- **Python** — the [Python API landing page](python/README.mdx) indexes every
+  curated module. Class methods and function signatures are pulled directly
+  from the source; there are no hand-maintained tables.
+- **Rust** — see the published [`ai-dynamo` crates on crates.io][crates] and
+  the [release artifact inventory](../general/release-artifacts.mdx) for
+  currently shipped crate versions.
+- **Kubernetes** — the [Kubernetes API reference](../kubernetes-api/full-api-reference.mdx)
+  documents the full DynamoGraphDeployment / DynamoComponentDeployment
+  custom-resource surface. Trimmed per-CRD references (DGD, DGDR, DCD) live
+  as siblings under the same section so every deep link resolves.
+
+## How It Stays Current
+
+The `docs/fern/scripts/gen_python_api.py` script parses the Dynamo Python
+source with [griffe][griffe] — no import, no build, no runtime dependency on
+backend containers. From one parse it writes:
+
+- the [Python API landing page](python/README.mdx) at
+  `docs/fern/pages/reference/api/python/README.mdx`, a card index of every
+  curated module.
+- `docs/fern/pages/reference/api/python/<module>.mdx` — one page per curated
+  module, with an anchored accordion per symbol carrying its import
+  statement, signature, and public methods.
+
+Every page is plain MDX built from Fern's own components, so the whole
+surface is indexed for search and Fern derives the Markdown and `llms.txt`
+twins from it directly.
+
+Run the generator locally after editing the Python source or the module list:
+
+```bash
+python3 docs/fern/scripts/gen_python_api.py            # write / refresh
+python3 docs/fern/scripts/gen_python_api.py --check    # drift check (exit 1 if stale)
+```
+
+`--check` is what CI runs against every commit to catch stale generated
+content before it ships.
+
+[griffe]: https://mkdocstrings.github.io/griffe/
+[crates]: https://crates.io/search?q=ai-dynamo

docs/fern/pages/reference/api/python/README.mdx

@@ -0,0 +1,24 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: Python API
+subtitle: Public Python surfaces on the Dynamo distributed runtime, statically discovered from the source tree.
+---
+
+{/* GENERATED by docs/fern/scripts/gen_python_api.py -- do not edit. */}
+
+Dynamo publishes 11 Python modules with 354 public class and function symbols under `dynamo.*`.
+
+<CardGroup cols={2}>
+<Card title="dynamo._core" href="python/_core">90 symbols. Rust-backed distributed runtime, KV router, and endpoint bindings.</Card>
+<Card title="dynamo.runtime" href="python/runtime">17 symbols. Decorators and re-exports for defining Dynamo workers and endpoints.</Card>
+<Card title="dynamo.llm" href="python/llm">46 symbols. High-level LLM primitives for building request pipelines.</Card>
+<Card title="dynamo.frontend" href="python/frontend">42 symbols. OpenAI-compatible HTTP frontend, argument parsing, and pre/post-processing.</Card>
+<Card title="dynamo.common" href="python/common">77 symbols. Shared configuration groups, storage adapters, and utility helpers.</Card>
+<Card title="dynamo.health_check" href="python/health_check">2 symbols. Health-check payload types and environment-driven configuration.</Card>
+<Card title="dynamo.logits_processing" href="python/logits_processing">4 symbols. Custom logits processors for LLM token generation.</Card>
+<Card title="dynamo.planner" href="python/planner">31 symbols. Scaling connectors, decision types, and Planner configuration.</Card>
+<Card title="dynamo.router" href="python/router">5 symbols. Request-router configuration and command-line argument groups.</Card>
+<Card title="dynamo.mocker" href="python/mocker">23 symbols. Mock engine used to run Dynamo workflows without a real GPU backend.</Card>
+<Card title="dynamo.nixl_connect" href="python/nixl_connect">17 symbols. NIXL RDMA connector primitives for KV cache and tensor transport.</Card>
+</CardGroup>