docs: add NIXL documentation (Fern platform) #1946
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # MILESTONES | ||
|
|
||
| ## v1.1 NIXLBench and KVBench Documentation (Shipped: 2026-04-07) | ||
|
|
||
| **Phases completed:** 6 phases, 9 plans, 10 tasks | ||
|
|
||
| **Key accomplishments:** | ||
|
|
||
| - Complete usage guide with etcd coordination, four communication patterns (pairwise, many-to-one, one-to-many, TP), GDS and OBJ storage examples, 18-flag CLI reference, and four troubleshooting sections with cross-links to all backend User Guide pages | ||
| - KVBench overview page with nixlbench subprocess relationship and command categories, plus build page with Docker cross-link and Python venv tabs | ||
| - Complete KVBench commands.md page (494 lines) with all 5 subcommand references, CLI argument tables, dual YAML schema documentation, and DeepSeek R1 / Llama 3.1 end-to-end examples | ||
| - Zero terminology drift found across all 6 benchmarking pages; added 2 missing first-mention cross-links (etcd on kvbench/commands, UCX on nixlbench/build) | ||
| - All 6 benchmarking pages pass fern check with zero errors and zero terminology violations on final re-sweep | ||
|
|
||
| --- | ||
|
|
||
| ## v1.0 — Initial Documentation (Completed) | ||
|
|
||
| **Goal:** Launch the full NIXL documentation site on Fern with complete coverage of all existing NIXL capabilities. | ||
|
|
||
| **Phases:** 21–31 (documentation polish, terminology, backends, getting started, user guide, examples, API ref, resources, cross-page coherency, overview, stack diagrams, architecture diagrams, examples reorder/expand, backend support matrix) | ||
|
|
||
| **Shipped:** | ||
|
|
||
| - Getting Started section (Overview, Architecture, Quick Start, Contributing) | ||
| - User Guide: all 13 backends, ETCD metadata exchange, telemetry | ||
| - Developer Guide: all build paths (Docker, C++, Python, Rust), backend plugin development | ||
| - Examples: 6 examples covering key NIXL usage patterns | ||
| - API Reference: C++, Python, Rust, Device, Plugin APIs | ||
| - Resources: Environment Variables, Troubleshooting | ||
| - Full NVIDIA branding, custom typography, dark/light theme | ||
|
|
||
| **Last phase:** 31 (examples reorder and expand) | ||
|
|
||
| --- | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| # NIXL Documentation | ||
|
|
||
| ## What This Is | ||
|
|
||
| The official documentation site for NVIDIA Inference Xfer Library (NIXL), built on the Fern platform. NIXL accelerates point-to-point communications in AI inference frameworks (e.g., NVIDIA Dynamo) and abstracts over memory types (CPU/GPU) and storage (file, block, object store) through a modular plugin architecture. This documentation site serves developers integrating or extending NIXL, including benchmarking tools for performance evaluation. | ||
|
|
||
| ## Core Value | ||
|
|
||
| Developers can find accurate, complete documentation for every NIXL capability — from quick start through advanced backend development and performance benchmarking — in one place. | ||
|
|
||
| ## Requirements | ||
|
|
||
| ### Validated | ||
|
|
||
| - ✓ Getting Started section (Overview, Architecture, Quick Start, Contribution Guide) — v1.0 | ||
| - ✓ User Guide: NIXL Backends (UCX, Libfabric, Mooncake, UCCL-P2P, DOCA GPUNetIO, GDS, GDS-MT, POSIX, HF3FS, OBJ, Azure Blob, GUSLI) — v1.0 | ||
| - ✓ User Guide: Metadata Exchange with ETCD, Telemetry Guide — v1.0 | ||
| - ✓ Developer Guide: Building from Source (Docker, C++/Meson, Python, Rust bindings), Building a Backend Plugin — v1.0 | ||
| - ✓ Examples: Basic Transfer, GDS Direct Storage, Remote Storage, NIXL-EP, ETCD Metadata Exchange, Telemetry Reader — v1.0 | ||
| - ✓ API Reference: C++, Python, Rust, Device, Plugin (Southbound) APIs — v1.0 | ||
| - ✓ Resources: Environment Variables, Troubleshooting — v1.0 | ||
| - ✓ Fern platform setup: custom NVIDIA branding, typography, colors, navbar, footer — v1.0 | ||
| - ✓ Terminology standards and cross-page coherence — v1.0 | ||
| - ✓ NIXLBench documentation: overview, build (Docker + native), usage guide, CLI reference, troubleshooting — v1.1 | ||
| - ✓ KVBench documentation: overview, build (Docker + venv), command reference (5 subcommands), model config schemas, LLM examples — v1.1 | ||
|
|
||
| ### Active | ||
|
|
||
| (None — awaiting next milestone definition) | ||
|
|
||
| ### Out of Scope | ||
|
|
||
| - Doxygen-generated C++ API detail pages — rendered separately via Doxygen, not Fern | ||
| - edit-this-page GitHub integration — ai-dynamo/nixl GitHub repo does not yet contain the fern/ directory | ||
| - AI-powered search — requires Fern Pro plan / Dashboard enablement | ||
| - NIXLBench full 70+ flag CLI reference — deferred; coverage via usage guide sufficient | ||
| - NIXLBench backend-specific deep-dive examples — backend User Guide pages already exist | ||
| - KVBench CTP examples — deferred | ||
| - KVBench GDS tutorial — deferred | ||
| - KVBench adding new model architecture guide — deferred | ||
|
|
||
| ## Context | ||
|
|
||
| - Built on Fern documentation platform, hosted at nixl.docs.buildwithfern.com | ||
| - Source lives in fern/ (config) and docs/ (markdown content) | ||
| - NVIDIA branding: NVIDIA green (#76B900), NVIDIA Sans font, dark/light theme | ||
| - v1.0 shipped Phases 21–31: all sections polished and cross-referenced | ||
| - v1.1 shipped Phases 32–37: 6 benchmarking pages (968 lines total), 18 requirements satisfied | ||
| - NIXLBench: C++ benchmark tool using etcd coordination, supports multiple network/storage backends and 4 communication patterns | ||
| - KVBench: Python tool that generates NIXLBench commands for KV cache transfer testing across LLM architectures (DeepSeek R1, Llama 3.1) | ||
|
|
||
| ## Constraints | ||
|
|
||
| - **Platform**: Fern — all pages must be valid MDX/Markdown compatible with Fern's parser | ||
| - **Branding**: NVIDIA brand guidelines — NVIDIA green accent, official fonts, no unauthorized logos | ||
| - **Content**: Must reflect actual NIXLBench/KVBench capabilities — no invented features | ||
|
|
||
| ## Key Decisions | ||
|
|
||
| | Decision | Rationale | Outcome | | ||
| |----------|-----------|---------| | ||
| | Fern platform | Structured, versioned docs with good DX and NVIDIA-compatible theming | ✓ Good | | ||
| | Separate products structure (versions at v1.0.0) | Enables future versioned docs as NIXL evolves | ✓ Good | | ||
| | docs/ for content, fern/ for config | Clean separation; aligns with Fern's recommended structure | ✓ Good | | ||
| | edit-this-page disabled | fern/ not yet in public ai-dynamo/nixl repo | — Pending | | ||
| | Benchmarking under User Guide (not Developer Guide) | User decision: benchmarking is user-facing, not dev-only | ✓ Good | | ||
| | Combined usage + troubleshooting page | User decision D-01: fewer pages, better discoverability | ✓ Good | | ||
| | NIXLBench CLI essentials only (not full 70+ flags) | Usage guide covers essentials; full reference deferred | ✓ Good | | ||
| | KVBench README CLI args only | Backend-specific args are passthrough, documented on backend pages | ✓ Good | | ||
|
|
||
| ## Evolution | ||
|
|
||
| This document evolves at phase transitions and milestone boundaries. | ||
|
|
||
| **After each phase transition** (via `/gsd-transition`): | ||
| 1. Requirements invalidated? → Move to Out of Scope with reason | ||
| 2. Requirements validated? → Move to Validated with phase reference | ||
| 3. New requirements emerged? → Add to Active | ||
| 4. Decisions to log? → Add to Key Decisions | ||
| 5. "What This Is" still accurate? → Update if drifted | ||
|
|
||
| **After each milestone** (via `/gsd-complete-milestone`): | ||
| 1. Full review of all sections | ||
| 2. Core Value check — still the right priority? | ||
| 3. Audit Out of Scope — reasons still valid? | ||
| 4. Update Context with current state | ||
|
|
||
| --- | ||
| *Last updated: 2026-04-07 after v1.1 milestone* |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # Project Retrospective | ||
|
|
||
| *A living document updated after each milestone. Lessons feed forward into future planning.* | ||
|
|
||
| ## Milestone: v1.1 — NIXLBench and KVBench Documentation | ||
|
|
||
| **Shipped:** 2026-04-07 | ||
| **Phases:** 6 | **Plans:** 9 | **Sessions:** ~4 | ||
|
|
||
| ### What Was Built | ||
| - 6 benchmarking documentation pages (968 lines total) under User Guide | ||
| - NIXLBench: overview, build (Docker + native), usage guide with 4 communication patterns, CLI reference, and troubleshooting | ||
| - KVBench: overview, build (Docker + Python venv), command reference for 5 subcommands, model config YAML schemas, DeepSeek R1 and Llama 3.1 end-to-end examples | ||
| - Full terminology normalization and cross-link audit across all new pages | ||
|
|
||
| ### What Worked | ||
| - Phase-per-page structure worked well for documentation — each phase produced one or two focused pages | ||
| - Research phase before each content phase caught edge cases (e.g., etcd underscore vs hyphen convention difference) | ||
| - Terminology normalization as a final phase caught 2 missing cross-links that individual phases missed | ||
| - fern check validation in Phase 37 confirmed zero errors across all pages | ||
|
|
||
| ### What Was Inefficient | ||
| - SUMMARY frontmatter `requirements_completed` not populated for early phases (32, 33) — caused bookkeeping gaps at audit time | ||
| - REQUIREMENTS.md traceability table not updated after each phase — 13/16 entries still showed "Pending" at milestone audit | ||
| - Directory path changed mid-milestone (Developer Guide → User Guide) requiring plan path updates in Phase 37 | ||
|
|
||
| ### Patterns Established | ||
| - Combined usage + troubleshooting into single page (user preference D-01) — reduces page count, improves discoverability | ||
| - Cross-link pattern: link backend names to User Guide pages on first mention per page | ||
| - CLI flag convention documentation: explicit note when two tools use different flag styles (underscores vs hyphens) | ||
|
|
||
| ### Key Lessons | ||
| 1. Update REQUIREMENTS.md traceability table after each phase completion, not just at audit time — prevents bookkeeping debt accumulation | ||
| 2. Confirm directory structure decisions before Phase 1 content authoring — the Developer Guide → User Guide move created unnecessary plan updates | ||
| 3. Documentation-only projects benefit from fern check as a continuous validation step, not just a final audit | ||
|
|
||
| ### Cost Observations | ||
|
Comment on lines
+10
to
+37
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win Add blank lines around section headings. Insert a blank line after each heading in this range to resolve the reported markdownlint warnings and keep the document consistently formatted. 🧰 Tools🪛 markdownlint-cli2 (0.23.0)[warning] 10-10: Headings should be surrounded by blank lines (MD022, blanks-around-headings) [warning] 16-16: Headings should be surrounded by blank lines (MD022, blanks-around-headings) [warning] 22-22: Headings should be surrounded by blank lines (MD022, blanks-around-headings) [warning] 27-27: Headings should be surrounded by blank lines (MD022, blanks-around-headings) [warning] 32-32: Headings should be surrounded by blank lines (MD022, blanks-around-headings) [warning] 37-37: Headings should be surrounded by blank lines (MD022, blanks-around-headings) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
| - Model mix: ~70% opus, ~30% sonnet (research phases used sonnet) | ||
| - Sessions: ~4 | ||
| - Notable: All 6 phases completed in a single day — documentation projects with clear source material (READMEs, --help output) move fast | ||
|
|
||
| --- | ||
|
|
||
| ## Cross-Milestone Trends | ||
|
|
||
| ### Process Evolution | ||
|
|
||
| | Milestone | Sessions | Phases | Key Change | | ||
| |-----------|----------|--------|------------| | ||
| | v1.0 | ~10 | 11 | Initial site buildout, established Fern patterns | | ||
| | v1.1 | ~4 | 6 | Added benchmarking docs, established cross-link and terminology patterns | | ||
|
|
||
| ### Top Lessons (Verified Across Milestones) | ||
|
|
||
| 1. Terminology normalization should be a dedicated final phase — catches drift that individual phases miss | ||
| 2. Cross-links to existing pages are better than duplicated content — reduces maintenance burden | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # Roadmap: NIXL Documentation | ||
|
|
||
| ## Milestones | ||
|
|
||
| - ✅ **v1.0 — Initial Documentation** — Phases 21–31 (shipped 2026-04-07) | ||
| - ✅ **v1.1 — NIXLBench and KVBench Documentation** — Phases 32–37 (shipped 2026-04-07) | ||
|
|
||
| --- | ||
|
|
||
| ## Phases | ||
|
|
||
| <details> | ||
| <summary>✅ v1.0 — Initial Documentation (Phases 21–31) — SHIPPED 2026-04-07</summary> | ||
|
|
||
| Phases 21–31 delivered the full NIXL documentation site on Fern: Getting Started, User Guide (13 backends, ETCD, telemetry), Developer Guide (all build paths, backend plugin), Examples (6 examples), API Reference (C++, Python, Rust, Device, Plugin APIs), Resources (environment variables, troubleshooting), and full NVIDIA branding with dark/light theming, terminology normalization, and cross-page coherency. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>✅ v1.1 — NIXLBench and KVBench Documentation (Phases 32–37) — SHIPPED 2026-04-07</summary> | ||
|
|
||
| Phases 32–37 added 6 benchmarking documentation pages (968 lines) under the User Guide: NIXLBench overview, build (Docker + native), usage guide with 4 communication patterns and troubleshooting; KVBench overview, build (Docker + Python venv), and command reference with model config schemas and DeepSeek R1 / Llama 3.1 end-to-end examples. All pages terminology-normalized and fern check clean. | ||
|
|
||
| - [x] Phase 32: Navigation and Directory Setup (2/2 plans) — completed 2026-04-07 | ||
| - [x] Phase 33: NIXLBench Overview and Build (1/1 plan) — completed 2026-04-07 | ||
| - [x] Phase 34: NIXLBench Usage, Troubleshooting, and Cross-References (2/2 plans) — completed 2026-04-07 | ||
| - [x] Phase 35: KVBench Overview and Build (1/1 plan) — completed 2026-04-07 | ||
| - [x] Phase 36: KVBench Commands, Model Config, and LLM Examples (1/1 plan) — completed 2026-04-07 | ||
| - [x] Phase 37: Terminology Normalization and Quality Audit (2/2 plans) — completed 2026-04-07 | ||
|
|
||
| </details> | ||
|
|
||
| --- | ||
|
|
||
| ## Progress | ||
|
|
||
| | Phase | Milestone | Plans Complete | Status | Completed | | ||
| |-------|-----------|----------------|--------|-----------| | ||
| | 21–31. v1.0 Documentation | v1.0 | Complete | Complete | 2026-04-07 | | ||
| | 32. Navigation and Directory Setup | v1.1 | 2/2 | Complete | 2026-04-07 | | ||
| | 33. NIXLBench Overview and Build | v1.1 | 1/1 | Complete | 2026-04-07 | | ||
| | 34. NIXLBench Usage, Troubleshooting, and Cross-References | v1.1 | 2/2 | Complete | 2026-04-07 | | ||
| | 35. KVBench Overview and Build | v1.1 | 1/1 | Complete | 2026-04-07 | | ||
| | 36. KVBench Commands, Model Config, and LLM Examples | v1.1 | 1/1 | Complete | 2026-04-07 | | ||
| | 37. Terminology Normalization and Quality Audit | v1.1 | 2/2 | Complete | 2026-04-07 | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| --- | ||
| gsd_state_version: 1.0 | ||
| milestone: v1.1 | ||
| milestone_name: — NIXLBench and KVBench Documentation | ||
| status: completed | ||
| stopped_at: Milestone v1.1 complete | ||
| last_updated: "2026-04-07T23:00:00.000Z" | ||
| last_activity: 2026-04-07 | ||
| progress: | ||
| total_phases: 6 | ||
| completed_phases: 6 | ||
| total_plans: 9 | ||
| completed_plans: 9 | ||
| percent: 100 | ||
| --- | ||
|
|
||
| # Project State | ||
|
|
||
| ## Project Reference | ||
|
|
||
| See: .planning/PROJECT.md (updated 2026-04-07) | ||
|
|
||
| **Core value:** Developers can find accurate, complete documentation for every NIXL capability in one place. | ||
| **Current focus:** Planning next milestone | ||
|
|
||
| ## Current Position | ||
|
|
||
| Phase: Complete | ||
| Plan: Complete | ||
| Status: v1.1 milestone shipped | ||
| Last activity: 2026-04-07 | ||
|
|
||
| Progress: [██████████] 100% (v1.1) | ||
|
|
||
| ## Performance Metrics | ||
|
|
||
| **Velocity:** | ||
|
|
||
| - Total plans completed: 9 (v1.1) | ||
| - Average duration: — | ||
| - Total execution time: 1 day | ||
|
|
||
| *Updated after each plan completion* | ||
|
|
||
| ## Accumulated Context | ||
|
|
||
| ### Decisions | ||
|
|
||
| - Fern platform is working; local dev requires `fern docs dev` from fern/ directory | ||
| - Benchmarking pages moved from Developer Guide to User Guide per user decision | ||
| - [Phase 36]: Documented README CLI args only; backend-specific args are passthrough documented on backend pages | ||
|
|
||
| ### Pending Todos | ||
|
|
||
| None. | ||
|
|
||
| ### Blockers/Concerns | ||
|
|
||
| - edit-this-page feature disabled pending public repo merge (see .planning/debug/edit-this-page-not-visible.md) | ||
| - AI search disabled pending Fern Pro plan (see .planning/debug/search-bar-no-entry-symbol.md) | ||
|
|
||
| ## Session Continuity | ||
|
|
||
| Last session: 2026-04-07 | ||
| Stopped at: Milestone v1.1 complete | ||
| Resume file: None |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the backend count.
This says “all 13 backends,” but
docs/index.ymllists 12 backend pages anddocs/getting-started/architecture.mdsays NIXL ships with 12 backends. Update the count or document the additional backend explicitly.🤖 Prompt for AI Agents