Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 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
218 changes: 141 additions & 77 deletions .agents/skills/dynamo-docs/SKILL.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions .github/FILTERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,12 @@ When you open a PR, CI checks which files changed and runs only relevant jobs:
| `benchmarks` | Dynamo runtime pipeline (runs `tests/benchmarks/**` pytest suite) |
| `sample` | Sample-backend unified test (piggybacks on vllm image) |
| `efa` | EFA runtime image builds for vLLM, SGLang, TRT-LLM (`container/templates/aws.Dockerfile` change) |
| `docs` | Nothing (classification only) |
| `docs` | Fern Configuration Check, Fern Broken Links Check, Docs Lint |
Comment thread
dmitry-tokarev-nv marked this conversation as resolved.
Resolved
| `examples` | Nothing (classification only) |
| `ignore` | Nothing (classification only) |
| `rust` | Rust pre merge checks |

> **Note:** `docs`, `examples`, `ignore`, and `sidecar` don't directly trigger CI jobs. They exist to satisfy coverage requirements - every file must match at least one filter. Sidecar source and proto files also match `rust`, which runs the workspace Rust checks.
> **Note:** `examples`, `ignore`, and `sidecar` don't directly trigger CI jobs. They exist to satisfy coverage requirements - every file must match at least one filter. Sidecar source and proto files also match `rust`, which runs the workspace Rust checks. `docs` does gate jobs: the Fern Configuration Check, Fern Broken Links Check, and Docs Lint jobs in `pre-merge.yml`.
Comment thread
dmitry-tokarev-nv marked this conversation as resolved.
Resolved

## Fixing "Uncovered Files" Errors

Expand Down
2 changes: 2 additions & 0 deletions .github/filters.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ docs:
- 'docs/**'
- 'fern/**'
- '.github/workflows/fern-docs.yml'
# `**` skips dotfile directories, so the `**/*.md` rule above misses this one.
- '.github/FILTERS.md'
- '**/*.md'
- '**/*.txt'
- '**/.gitignore'
Expand Down
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 docs/fern/scripts/docs_lint.py --scan docs --github

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
60 changes: 58 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,55 @@ 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.
`docs/fern/scripts/docs_lint.py` enforces the deterministic subset 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)).

The linter separates the rules that fail the job from the ones it only reports:

| | Rules |
|---|---|
| **Blocking** (job fails) | Missing or misplaced SPDX header; frontmatter with no YAML key; a relative link that breaks or escapes `docs/`; a dangling `path:` in `index.yml`; a tracker ID or NVBug reference |
| **Advisory** (annotated, does not fail) | Body `# H1`; `TODO`/`FIXME`; internal-looking host; hardcoded `docs.nvidia.com` self-link; a page file missing from the nav |

Two rules are advisory for a reason: the generated Kubernetes API reference carries a body `# H1`
that comes from the `crd-ref-docs` template rather than the page, and a `TODO` sometimes marks a
page whose fate is an open decision. Advisory does not mean optional — fix them in the pages you
touch. The CI job scans `docs/` only; run the linter with its default `--scan docs,examples,recipes`
before changing an example or recipe README.

## 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 |
| `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 docs/fern/scripts/docs_lint.py --scan docs # the `Docs Lint` pull request job
python3 docs/fern/scripts/docs_lint.py # same rules over docs + examples + recipes
Comment thread
dagil-nvidia marked this conversation as resolved.
Resolved
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).
11 changes: 9 additions & 2 deletions docs/fern/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -395,8 +395,10 @@ redirects:
destination: "/dynamo/dev/kubernetes/getting-started/quickstart"
- source: "/dynamo/kubernetes-deployment/start-here/minikube-setup"
destination: "/dynamo/dev/cli/installation/minikube-setup"
# The Examples reference page was an empty stub and has been removed. Worked, runnable
# deployments live in the recipes catalog, so both Examples URLs land there.
- source: "/dynamo/resources/examples"
destination: "/dynamo/dev/reference/examples"
destination: "/dynamo/dev/recipes/browse"
- source: "/dynamo/resources/feature-matrix"
destination: "/dynamo/dev/reference/compatibility"
- source: "/dynamo/resources/glossary"
Expand Down Expand Up @@ -561,7 +563,12 @@ redirects:
- source: "/dynamo/dev/getting-started/release-artifacts"
destination: "/dynamo/dev/reference/release-artifacts"
- source: "/dynamo/dev/getting-started/examples"
destination: "/dynamo/dev/reference/examples"
destination: "/dynamo/dev/recipes/browse"
# The pages themselves were empty stubs and are gone; keep their dev URLs serving.
- source: "/dynamo/dev/reference/examples"
destination: "/dynamo/dev/recipes/browse"
- source: "/dynamo/dev/kubernetes/installation/model-storage/overview"
destination: "/dynamo/dev/kubernetes/installation/model-storage/aks-storage"
Comment thread
dmitry-tokarev-nv marked this conversation as resolved.
Resolved
- source: "/dynamo/dev/fastokens-tokenizer"
destination: "/dynamo/dev/advanced-customizations/fastokens-tokenizer"
- source: "/dynamo/v1.0.1/getting-started/support-matrix"
Expand Down
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
Loading
Loading