Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
db49ba9
ci: add a blocking docs lint job
dagil-nvidia Aug 1, 2026
28aa087
docs: realign the agent guides with the tab-based docs structure
dagil-nvidia Aug 1, 2026
1f43c8b
ci: cover docs_lint.py and FILTERS.md in the docs filter
dagil-nvidia Aug 1, 2026
c8d7ea4
fix(docs-lint): correct line offsets, fence blanking, and rule coverage
dagil-nvidia Aug 1, 2026
583ec96
docs: correct the agent guides on templates, redirects, and lint scope
dagil-nvidia Aug 1, 2026
728bf2c
refactor(docs-lint): move the linter under docs/fern/scripts
dagil-nvidia Aug 2, 2026
299f323
Merge branch 'main' into dagil-nvidia/docs-agent-guides-and-lint
dagil-nvidia Aug 2, 2026
504de56
Merge remote-tracking branch 'origin/main' into u12528
dagil-nvidia Aug 5, 2026
b1232d8
Merge remote-tracking branch 'origin/main' into v12528
dagil-nvidia Aug 5, 2026
77e73df
fix(docs): address review on the docs linter and filters
dagil-nvidia Aug 10, 2026
82e68b0
docs: use absolute GitHub URLs for the links that escape recipes/
dagil-nvidia Aug 10, 2026
4671064
ci: stop repo-wide markdown from triggering the Fern docs jobs
dagil-nvidia Aug 10, 2026
40ed50b
docs(ci): say which markdown belongs in docs and which in ignore
dagil-nvidia Aug 10, 2026
23857e2
Revert the recipe links to relative
dagil-nvidia Aug 10, 2026
41d48a4
docs(agents): generalize the generated-artifact rule
dagil-nvidia Aug 10, 2026
ba8b713
docs(agents): keep the root guide to the repo-wide rule
dagil-nvidia Aug 10, 2026
ee00518
docs: drop the example and recipe lint sweep from this branch
dagil-nvidia Aug 10, 2026
00fdbcc
fix: restore the operator header input for the generated k8s reference
dagil-nvidia Aug 10, 2026
7af69c1
Merge origin/main, keeping the accurate docs-filter row
dagil-nvidia Aug 10, 2026
99813a2
Merge origin/main after #12110
dagil-nvidia Aug 11, 2026
6cf2786
Merge origin/main
dagil-nvidia Aug 11, 2026
5324137
Merge origin/main into docs-agent-guides-and-lint
dagil-nvidia Aug 12, 2026
91466e9
docs: scope the docs linter to docs/ and drop the examples/recipes cl…
dagil-nvidia Aug 12, 2026
ab0cc26
Merge remote-tracking branch 'origin/main' into pr12528-update
dagil-nvidia Aug 22, 2026
2af874d
Merge origin/main into docs-agent-guides-and-lint
dagil-nvidia Sep 1, 2026
d99da1b
Merge origin/main into docs-agent-guides-and-lint
dagil-nvidia Sep 1, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 129 additions & 74 deletions .agents/skills/dynamo-docs/SKILL.md

Large diffs are not rendered by default.

18 changes: 17 additions & 1 deletion .github/workflows/pre-merge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ jobs:

pre-merge-status-check:
runs-on: ubuntu-latest
needs: [changed-files, pre-commit, fern-check, fern-broken-links, operator, snapshot, rust-tests, rust-clippy]
needs: [changed-files, pre-commit, fern-check, fern-broken-links, docs-lint, operator, snapshot, rust-tests, rust-clippy]
if: always()
steps:
- name: "Check all dependent jobs"
Expand Down Expand Up @@ -83,6 +83,22 @@ jobs:
working-directory: docs/fern
run: fern check

# Structural docs rules the Fern CLI does not cover: SPDX headers, frontmatter, body H1,
# link scope, dangling nav paths, and internal references. Read-only, so it reports through
# inline annotations and the job summary rather than a pull request comment.
docs-lint:
name: Docs Lint
needs: changed-files
if: needs.changed-files.outputs.docs == 'true'
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
- name: Lint docs structure
run: python3 scripts/docs_lint.py --scan docs --github
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved

fern-broken-links:
name: Fern Broken Links Check
needs: changed-files
Expand Down
15 changes: 10 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,16 +79,16 @@ Sibling repositories this repo integrates with:
| `components/src/dynamo/` | Python packages: `frontend`, `planner`, `router`, `vllm`/`sglang`/`trtllm` backends, `mocker`, `profiler`, and more |
| `deploy/` | Kubernetes `operator`, Helm charts, `inference-gateway` ext-proc, `observability` |
| `container/` | Dockerfiles and build scripts for runtime and dev images |
| `docs/`, `fern/` | Documentation sources and the Fern docs-site config — read [`docs/AGENTS.md`](docs/fern/AGENTS.md) before editing |
| `examples/`, `recipes/` | Runnable examples and deployment recipes — also covered by [`docs/AGENTS.md`](docs/fern/AGENTS.md) |
| `docs/fern/` | Fern docs site: `pages/` holds every page, the rest is site config (`index.yml`, `docs.yml`, `main.css`, `components/`, `scripts/`, `translations/`). Read [`docs/fern/AGENTS.md`](docs/fern/AGENTS.md) before editing, and [`docs/fern/pages/AGENTS.md`](docs/fern/pages/AGENTS.md) before adding a page |
| `examples/`, `recipes/` | Runnable examples and deployment recipes — also covered by [`docs/fern/AGENTS.md`](docs/fern/AGENTS.md) |
| `benchmarks/`, `tests/` | Benchmark harnesses and the top-level pytest suite |
| `.ai/` | Agent topic guidelines: `bash-launch-guidelines.md`, `ci-guidelines.md`, `linear-ticket-refs.md`, `pytest-guidelines.md`, `python-guidelines.md`, `test-model-size-guardrails.md` |
| `.agents/skills/` | Agent skills (see [Skills](#skills)) |

## Build

System prerequisites (Rust toolchain, `uv`, system libraries) and the VS Code / Cursor
devcontainer are covered in [`docs/contribution-guide.md`](docs/fern/pages/community/contributing/overview.md).
devcontainer are covered in [the contribution guide](docs/fern/pages/community/contributing/overview.md).

Python dev build (bindings + wheel, editable):

Expand Down Expand Up @@ -146,13 +146,18 @@ cargo fmt --all && cargo clippy --workspace
- Architecture changes require a Dynamo Enhancement Proposal (DEP), filed as a GitHub
issue on `ai-dynamo/dynamo` with `dep:*` labels (the `dep-create` skill automates this).

See [`docs/contribution-guide.md`](docs/fern/pages/community/contributing/overview.md) for the full workflow
See [the contribution guide](docs/fern/pages/community/contributing/overview.md) for the full workflow
(issue sizing, CODEOWNERS, review process).

## Docs, Examples, Recipes

Any change under `docs/`, `examples/`, or `recipes/` must follow
[`docs/AGENTS.md`](docs/fern/AGENTS.md) and the
[`docs/fern/AGENTS.md`](docs/fern/AGENTS.md) and the
[documentation style guide](docs/fern/pages/community/contributing/documentation/documentation-style-guide.md): SPDX headers, Fern
frontmatter (no body `# H1`), GitHub-style admonitions, and backend casing
(vLLM / SGLang / TensorRT-LLM). The deterministic subset is enforced pre-merge.

The docs site is tab-based: `docs/fern/pages/` splits into `kubernetes/` and `cli/` (parallel
guides for two readers), plus `use-cases/`, `recipes/`, `developer-guide/`, `reference/`, `blog/`,
and `community/`. Read [`docs/fern/pages/AGENTS.md`](docs/fern/pages/AGENTS.md) to pick the right
tab before adding a page — a misplaced page costs a move plus a redirect.
1 change: 1 addition & 0 deletions deploy/operator/docs/header.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
sidebar-title: API Reference (K8s)
---

> **⚠️ Important**: This documentation is automatically generated from source code.
Expand Down
48 changes: 46 additions & 2 deletions docs/fern/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,18 @@ SPDX-License-Identifier: Apache-2.0
# Agent instructions — docs, examples, recipes

When creating or editing files under `docs/`, `examples/`, or `recipes/`, follow the
[documentation style guide](pages/community/contributing/documentation/documentation-style-guide.md). Non-negotiables:
[documentation style guide](pages/community/contributing/documentation/documentation-style-guide.md).
For **where** a new page belongs in the tab structure, read
[`pages/AGENTS.md`](pages/AGENTS.md) first — placement is decided before anything below matters.

## Authoring non-negotiables

- SPDX header on every file: frontmatter `#` form for Fern docs, `<!-- -->` for plain READMEs,
full Apache block for code/config; copyright range `2025-2026`.
- Fern docs: `---` frontmatter with SPDX + at least one metadata key (`title`/`subtitle`/
`sidebar-title`). Fern renders the page H1 from the nav `page:`, so do **not** add a body `# H1`
(it duplicates the title); start the body at `##`.
- Every new page needs a `- page:` entry in `index.yml`. A page not in the nav is unreachable.
- Admonitions follow the source extension: use Fern callout components (`<Note>`, `<Tip>`,
`<Info>`, `<Warning>`, `<Error>`) in `.mdx`, and GitHub-style blockquotes (`> [!NOTE]`) in `.md`.
- Links: relative + extension within `docs/`; absolute `github.com/ai-dynamo/dynamo` URLs for
Expand All @@ -21,4 +26,43 @@ When creating or editing files under `docs/`, `examples/`, or `recipes/`, follow
- No internal/sensitive refs (NVBug/JIRA IDs, internal hosts, secrets, TODO/FIXME) in shipped docs.
- Write for humans: no marketing/bombast, no filler, be concrete.

The Dynamo Docs Bot enforces the deterministic subset pre-merge.
`scripts/docs_lint.py` enforces the deterministic subset (SPDX, frontmatter, body `# H1`, link
scope, dangling nav paths, internal references) as the `Docs Lint` job on every pull request, and
`fern check` plus `fern docs broken-links` run alongside it. Reproduce all three locally before
pushing (see [Validate](#validate)).

## This directory

`docs/fern/` holds both the content tree and the site configuration. Content lives in `pages/`;
everything else here is machinery:

| Path | Role |
|---|---|
| `pages/` | Every docs page — see [`pages/AGENTS.md`](pages/AGENTS.md) |
| `index.yml` | Navigation: tab map + per-tab layout. The only place a page becomes reachable |
| `docs.yml` | Site config, locales, landing page, versions, and `redirects:` |
| `main.css` | Site styles, including the pure-CSS recipe target-picker vocabulary |
| `components/` | React `.tsx` components used by `.mdx` pages |
| `templates/` | Page skeletons for new backend, component, and feature docs |
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
| `scripts/` | Build and sync tooling (callout conversion, translation links, snapshot rewrites) |
| `translations/` | Locale mirrors of `pages/` (`zh-CN/pages/<same relative path>`) |
| `assets/` | Images, diagrams, fonts |

Two gates on the machinery:

- Editing `main.css` requires running `python3 docs/fern/scripts/sync_site_css.py` so the footer's
CSS mirror stays in sync. Pre-commit enforces this.
- The `docs-website` branch is CI-managed and must **never** be edited by hand. All authoring
happens on `main` or a feature branch based on it.

## Validate

```bash
python3 scripts/docs_lint.py --scan docs # the `Docs Lint` pull request job
fern check # nav + frontmatter structure
fern docs broken-links # link resolution
python3 docs/fern/pages/recipes/_catalog/validate.py # recipe or benchmark changes only
```

For how the site builds and publishes, see
[Building and Publishing](pages/community/contributing/documentation/building-and-publishing.md).
4 changes: 0 additions & 4 deletions docs/fern/index.yml
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,6 @@ navigation:
path: pages/kubernetes/installation/rdma-setup/efa-on-aws.mdx
- section: Model Storage
contents:
- page: Overview
path: pages/kubernetes/installation/model-storage/overview.md
- page: AKS Storage
path: pages/kubernetes/installation/model-storage/aks-storage.md
- page: Azure Lustre CSI Driver
Expand Down Expand Up @@ -929,8 +927,6 @@ navigation:
layout:
- page: Compatibility
path: pages/reference/general/compatibility.mdx
- page: Examples
path: pages/reference/general/examples.md
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
- page: Release Artifacts
path: pages/reference/general/release-artifacts.mdx
- section: Releases
Expand Down
133 changes: 133 additions & 0 deletions docs/fern/pages/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Agent instructions — docs content and placement

This directory holds every page on the Dynamo docs site. It covers **where a page goes**;
[`../AGENTS.md`](../AGENTS.md) covers **how a page is written** (SPDX, frontmatter, callouts, links),
and the [documentation style guide](community/contributing/documentation/documentation-style-guide.md)
is the full standard. Read all three before adding a page.

The site is tab-based. Placing a page in the wrong tab is the most common and most expensive mistake
here, because the fix is a move plus a redirect.

## Tabs

Nine tabs, each rooted at one directory. The nav key in `docs/fern/index.yml` and the directory name
differ for two of them — match on the directory.

| Tab (nav key) | Directory | Holds |
|---|---|---|
| `home` | `home/` | The landing page. Do not add pages here. |
| `kubernetes-guide` | `kubernetes/` | Deploying and operating Dynamo **on Kubernetes** |
| `cli-guide` | `cli/` | Running Dynamo **from the CLI** on local or bare-metal hosts |
| `use-cases` | `use-cases/` | Workload-shaped guides (agents, multimodal, diffusion, RL, tool calling) |
| `recipes` | `recipes/` | Model recipes, deployment templates, feature benchmarks |
| `developer-guide` | `developer-guide/` | Internals, architecture, customization, contributor-facing knowledge |
| `reference` | `reference/` | Exact contracts: APIs, CRDs, flags, metrics, releases, compatibility |
| `blog` | `blog/` | Dated posts under a year directory |
| `community` | `community/` | Contributing, governance, community process |

## The Kubernetes / CLI split

`kubernetes/` and `cli/` are **parallel guides for two different readers**, not a topic hierarchy.
They share most section names:

```
kubernetes/ getting-started installation model-deployment kv-aware-routing
disaggregated-serving kv-cache-offloading operations
fault-tolerance auto-deployment <- Kubernetes only

cli/ getting-started installation model-deployment kv-aware-routing
disaggregated-serving kv-cache-offloading operations
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

A feature page belongs to the surface its instructions target:

- Manifests, Helm, CRDs, operator behavior, or `kubectl` → `kubernetes/`.
- `dynamo` / `python3 -m dynamo.*` commands, local processes, env vars → `cli/`.
- Both, in substance → **two pages**, one per tab, each complete for its reader. Do not write one
page that branches on deployment surface halfway through, and do not cross-link a CLI reader into
the Kubernetes tab for a step they need.
- Neither — the contract itself, independent of how it is launched → `reference/`.

## Choosing a tab

Work down this list and stop at the first match:

1. Is it an exact contract (flag, field, endpoint, metric, CRD, version matrix)? → `reference/`
2. Is it a dated announcement or narrative post? → `blog/`
3. Is it about contributing to Dynamo itself? → `community/`
4. Is it a model recipe, a deployment template, or a benchmark? → `recipes/`, and follow
[`recipes/_catalog/README.md`](recipes/_catalog/README.md) — those pages are a triple (page +
catalog entry + nav), never a lone file.
5. Is it organized around a workload rather than a deployment step? → `use-cases/`
6. Is it internals, architecture, or customization for someone extending Dynamo? → `developer-guide/`
7. Otherwise it is a deployment or operations task → `kubernetes/` or `cli/` per the split above.

Then place the file next to the **nearest existing page on the same topic** within that tab, and
reuse that sibling's subdirectory. Read `docs/fern/index.yml` for the live structure; the section
lists in this file are a snapshot and will drift.

Prefer extending an existing page over adding a new one. A new page has to earn a nav slot.

## Navigation

`docs/fern/index.yml` is the source of truth and the only place a page becomes reachable. A page not
in the nav is dead content.

- The file opens with a `tabs:` map (`display-name`, `icon`, and either `slug:` or `skip-slug: true`),
then a `navigation:` list of `- tab: <key>` entries, each with a `layout:`.
- Under `layout:`, content is either a `- section:` with `contents:` (sections nest) or a bare
`- page:`. Sections are marked by a banner comment:
`# ==================== <Section> ====================`.
- `path:` is relative to `docs/fern/`, so it always starts with `pages/`.
- `- link:` points at a URL instead of a file — used to surface one tab's page from another. It does
not move the page.
- Page keys worth knowing: `slug:` overrides the label-derived slug, `hidden: true` keeps a page
reachable by URL but off the sidebar, `collapsed: open-by-default` expands a section, `icon:` sets
the sidebar glyph.

### URLs and redirects

A page's URL is built by joining the slug of each nav level that contributes one: tab, then section
(sections nest), then the page. Slugs come from the `- page:` / `- section:` **label**, not the file
path, unless an explicit `slug:` overrides it. A level carrying `skip-slug: true` contributes no
segment — but its children still do, so a page under a skip-slug tab lands under its *section* slug,
not at the site root. `pages/developer-guide/advanced-customizations/building-from-source.md` serves
at `/dynamo/dev/advanced-customizations/building-from-source`: the tab is skipped, the section is
not.

Two consequences:

- Renaming a `- page:` label changes the URL even when the file does not move.
- Moving a file between directories changes nothing unless the label or section changes.

Either way, add a **dev-scoped** redirect to `redirects:` in `docs/fern/docs.yml`
(`/dynamo/dev/<old>` → `/dynamo/dev/<new>`). Do not redirect the unversioned or `/dynamo/latest/`
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
forms — those serve a frozen release snapshot that `main` edits do not touch, and a redirect there
breaks a working URL.

## Assets and translations

- Images live in `docs/fern/assets/img/`, referenced by a relative path from the page
(`../../../assets/img/<name>.svg`) with descriptive alt text. Blog posts use their own
`blog/_assets/` tree instead.
- Chinese translations mirror the English page at
`docs/fern/translations/zh-CN/pages/<same relative path>` — same file name, same SPDX header,
Chinese frontmatter, no body `# H1`. Fern's native localization pairs them and falls back to
English for untranslated pages. Translate prose only: code, flags, and product names
(vLLM / SGLang / TensorRT-LLM) stay verbatim. A stale translation is worse than a missing one.

## Validate

```bash
fern check # nav + frontmatter structure
fern docs broken-links # link resolution
python3 docs/fern/pages/recipes/_catalog/validate.py # recipe or benchmark changes only
```

`fern check` and `broken-links` mirror the pre-merge checks. The catalog validator is not wired into
CI — run it by hand for any `_catalog/` change.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
5 changes: 5 additions & 0 deletions docs/fern/pages/blog/_assets/flash-indexer/tools/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Flash Indexer Figures -- Reproduction Guide

Build instructions for all Flash Indexer Digest post figures.
Expand Down
Loading
Loading