From d4ace490e75e62d1bb46db479b310941c91732e4 Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 27 Oct 2026 16:40:56 +0000 Subject: [PATCH 01/15] docs: publish llms.txt and Markdown pages with sphinx-llm Agents read Markdown more reliably than themed HTML. sphinx-llm now writes an llms.txt index and a page.md beside every page.html of the main docs; release branches and tags keep HTML only. The site root gets a static llms.txt pointing at main's. The Markdown builder drops nodes it has no visitor for, and CI holds it to -W, so markdown_nodes renders captions, admonitions and card titles. The ecosystem device tables stay out of the Markdown. The HTML output only gains two elements per page. Signed-off-by: Jakob Bornecrantz --- REUSE.toml | 7 ++++ docs/AGENTS.md | 13 ++++++ docs/Makefile | 1 + docs/llms.txt | 9 +++++ docs/requirements.txt | 2 + docs/source/_ext/ecosystem_grid.py | 1 + docs/source/_ext/markdown_nodes.py | 65 ++++++++++++++++++++++++++++++ docs/source/conf.py | 20 +++++++++ docs/source/overview/ecosystem.rst | 20 ++++++--- 9 files changed, 132 insertions(+), 6 deletions(-) create mode 100644 docs/llms.txt create mode 100644 docs/source/_ext/markdown_nodes.py diff --git a/REUSE.toml b/REUSE.toml index 38c21963fb..754b83e07f 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -30,6 +30,13 @@ precedence = "override" SPDX-FileCopyrightText = "Copyright (c) NVIDIA CORPORATION & AFFILIATES. All rights reserved." SPDX-License-Identifier = "Apache-2.0" +# llms.txt files stay plain Markdown for agents, so their REUSE info lives here. +[[annotations]] +path = "docs/llms.txt" +precedence = "override" +SPDX-FileCopyrightText = "Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved." +SPDX-License-Identifier = "Apache-2.0" + [[annotations]] path = "examples/cloudxr_mujoco_teleop/**" precedence = "override" diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 93107f634d..d97db575e5 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -44,6 +44,19 @@ that references it. Stage new artwork with a plain `git add` before running pre- whose hooks pre-commit installed has no LFS pre-push hook, so GitHub declines a push that adds artwork; run `git lfs push origin ` first. +## Agents read a Markdown build of every page + +sphinx-llm runs a second, Markdown build, and `make current-docs` holds it to `-W` too. +sphinx-markdown-builder drops any node it has no visitor for, children included, and +warns. Give such a node a `markdown` visitor, in `_ext/markdown_nodes.py` or in the +extension that owns the node, and list nodes that only matter in HTML in +`llms_txt_suppress_unknown_node_warnings`. To leave a block out of the Markdown, use +`.. only:: not sphinx_llm_markdown`: sphinx-llm 1.1.0 has no `human` or `agent` tag, and +it forwards the HTML build's tags, `html` included, to the Markdown build. + +sphinx-llm treats every `*.md` in its output as a page, `:download:` copies included. +Keep non-page output paths in `llms_txt_exclude`, not out of the docs. + ## Device pages stand alone `docs/source/device/*.rst` is what the public site renders. A `:code-file:` diff --git a/docs/Makefile b/docs/Makefile index 5cb07adbfd..219d6cf290 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -18,3 +18,4 @@ current-docs: multi-docs: @sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) @cp index.html $(BUILDDIR)/index.html + @cp llms.txt $(BUILDDIR)/llms.txt diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000000..ab3a56faca --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,9 @@ +# Isaac Capture + +> Shared capture infrastructure for teleoperation and egocentric data. + +The documentation is published per version below this site root. Only `main` publishes an index and Markdown pages for agents for now: replace `.html` with `.md` in any of its page URLs. + +## Docs + +- [Isaac Capture documentation (main)](https://nvidia.github.io/IsaacCapture/main/llms.txt): index of every page on main, each linked as Markdown diff --git a/docs/requirements.txt b/docs/requirements.txt index d64436dbac..7e74ce781e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,4 +3,6 @@ sphinx-copybutton==0.5.2 sphinx-multiversion==0.2.4 sphinx==8.1.3 sphinx-design==0.6.1 +sphinx-llm==1.1.0 +sphinx-markdown-builder==0.6.11 pyyaml==6.0.2 diff --git a/docs/source/_ext/ecosystem_grid.py b/docs/source/_ext/ecosystem_grid.py index 8c80a5d353..0e57c75d75 100644 --- a/docs/source/_ext/ecosystem_grid.py +++ b/docs/source/_ext/ecosystem_grid.py @@ -750,6 +750,7 @@ def setup(app): app.add_node( node_class, html=(_visit_eco_block, _depart_eco_block), + markdown=(_passthrough, _passthrough), latex=(_passthrough, _passthrough), text=(_passthrough, _passthrough), man=(_passthrough, _passthrough), diff --git a/docs/source/_ext/markdown_nodes.py b/docs/source/_ext/markdown_nodes.py new file mode 100644 index 0000000000..72fb96f27c --- /dev/null +++ b/docs/source/_ext/markdown_nodes.py @@ -0,0 +1,65 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Markdown for nodes that sphinx-markdown-builder has no visitor for. + +That builder drops an unknown node together with its children, so without these the +``page.md`` copies sphinx-llm publishes lose captions, generic admonitions and +sphinx-design card titles. Nodes that only matter in HTML are silenced in ``conf.py``. +""" + +from __future__ import annotations + +from docutils import nodes +from sphinx_design.shared import PassthroughTextElement + + +def _visit_as_paragraph(self, node): + self.visit_paragraph(node) + + +def _depart_as_paragraph(self, node): + self.depart_paragraph(node) + + +def _visit_admonition(self, node): + """A generic admonition becomes a heading line followed by its body.""" + title = node[0] if node.children and isinstance(node[0], nodes.title) else None + if title is not None: + self.add(f"#### {title.astext()}", prefix_eol=2) + for child in node.children: + if child is not title: + child.walkabout(self) + raise nodes.SkipNode + + +def _is_card_title(node): + return "sd-card-title" in node.parent.get("classes", []) + + +def _visit_card_text(self, node): + """Card titles render bold; the same element also wraps a card's stretched link.""" + self.visit_paragraph(node) + if _is_card_title(node): + self.add("**") + + +def _depart_card_text(self, node): + if _is_card_title(node): + self.add("**") + self.depart_paragraph(node) + + +def setup(app): + app.add_node( + nodes.caption, + override=True, + markdown=(_visit_as_paragraph, _depart_as_paragraph), + ) + app.add_node(nodes.admonition, override=True, markdown=(_visit_admonition, None)) + app.add_node( + PassthroughTextElement, + override=True, + markdown=(_visit_card_text, _depart_card_text), + ) + return {"version": "1.0", "parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/source/conf.py b/docs/source/conf.py index 26c4d3ea6e..a6ce111e98 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -68,6 +68,8 @@ def _pip_pin(ref_name, fallback): "sphinx_design", "ecosystem_grid", "breakable_literals", + "markdown_nodes", + "sphinx_llm.txt", ] exclude_patterns = ["build", "_templates", "_data", "_ext", "Thumbs.db", ".DS_Store"] @@ -78,6 +80,24 @@ def _pip_pin(ref_name, fallback): # to keep the copy button on them. copybutton_selector = "div.highlight pre, pre.literal-block" +# sphinx-llm writes llms.txt and a page.md beside every page.html for agents. Only main +# publishes them; plain sphinx-build ("") keeps them on so CI's -W covers the Markdown +# build too. +llms_txt_enabled = _smv_ref_name() in ("", "main") +llms_txt_suffix_mode = "replace" +# A redirect stub's refresh and a hidden toctree mean nothing outside HTML. +llms_txt_suppress_unknown_node_warnings = ["meta", "toctree"] +# sphinx-llm indexes every *.md in its build, so a :download: of a README.md would be +# listed as a page with no doctree, which -W turns into a failure. +llms_txt_exclude = ["_downloads/**"] +# The default is pyproject.toml's description, which still reads "Isaac Teleop". +llms_txt_description = ( + "Isaac Capture is shared capture infrastructure for teleoperation (Isaac Teleop) " + "and egocentric data (Ego Pipeline): device plugins, retargeters, and data " + "utilities for recording, replaying, and converting human and robot " + "demonstration data." +) + templates_path = ["_templates"] # sphinx-multiversion: which refs to build (avoids "No matching refs found" in CI) diff --git a/docs/source/overview/ecosystem.rst b/docs/source/overview/ecosystem.rst index f2d9de394e..c949d20bb6 100644 --- a/docs/source/overview/ecosystem.rst +++ b/docs/source/overview/ecosystem.rst @@ -29,8 +29,12 @@ A standardized device interface removes custom integrations and their maintenanc modes determine which retargeters and control schemes are available. :doc:`Add a new device → ` -.. device-matrix:: - :section: input +.. The device tables are interactive HTML layout; the Markdown build for agents leaves them out. + +.. only:: not sphinx_llm_markdown + + .. device-matrix:: + :section: input .. _data-factory: @@ -42,8 +46,10 @@ Data Factory :device-count:`data_factory` Frameworks and services for collecting teleoperation data and turning it into training datasets. -.. device-matrix:: - :section: data_factory +.. only:: not sphinx_llm_markdown + + .. device-matrix:: + :section: data_factory .. _cloud-infrastructure: @@ -54,8 +60,10 @@ Cloud Infrastructure :device-count:`cloud` Cloud platforms available for running Isaac Capture workloads. -.. device-matrix:: - :section: cloud +.. only:: not sphinx_llm_markdown + + .. device-matrix:: + :section: cloud .. rst-class:: eco-section From 35d1519b2d7a33c3d6ac0f758e01fc228ece646b Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 27 Oct 2026 16:43:45 +0000 Subject: [PATCH 02/15] feat(skills): add skills index and isaac-capture-install skills/ holds Agent Skills for people using Isaac Capture in their own projects, indexed by skills/README.md. The reBot skill stays with its example and is linked by URL. isaac-capture-install sets up a uv venv, picks extras, installs from PyPI and checks the import. It defers to the Quick Start. Signed-off-by: Jakob Bornecrantz --- skills/README.md | 16 +++++ skills/isaac-capture-install/SKILL.md | 92 +++++++++++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 skills/README.md create mode 100644 skills/isaac-capture-install/SKILL.md diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000000..89046c3b54 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ + + +# Isaac Capture skills + +Task-level skills for coding agents that work with Isaac Capture in their own +projects. Each skill is a directory holding a `SKILL.md` in the +[Agent Skills](https://agentskills.io) format. + +- [isaac-capture-install](isaac-capture-install/SKILL.md): install the `isaaccapture` + package into a uv virtual environment, choose its extras, and check that it imports. +- [rebot-orin-setup](https://github.com/NVIDIA/IsaacCapture/blob/main/examples/rebot/SKILL.md): + bring up a reBot B601-RS arm from a Jetson AGX Orin over its built-in CAN. It lives + with the reBot example. diff --git a/skills/isaac-capture-install/SKILL.md b/skills/isaac-capture-install/SKILL.md new file mode 100644 index 0000000000..51c41048be --- /dev/null +++ b/skills/isaac-capture-install/SKILL.md @@ -0,0 +1,92 @@ +--- +name: isaac-capture-install +description: >- + Use when installing Isaac Capture (the isaaccapture Python package, formerly + isaacteleop) into a project: creating a uv virtual environment, choosing extras + (cloudxr, retargeters, retargeters-lite, ui, grounding, wuji), installing a stable + or pre-release build from PyPI, and checking that the install imports. +--- + + + +# Install Isaac Capture + +Install the `isaaccapture` package from PyPI into a virtual environment, then check +that it imports. The +[Quick Start](https://nvidia.github.io/IsaacCapture/main/teleop/quick_start.md) is the +source of truth for these commands; follow it wherever it disagrees with this skill. + +## 1. Create a virtual environment + +Python 3.11 to 3.13 are supported. Install into a virtual environment: outside one, +`pip install` fails on Ubuntu 24.04 with `externally-managed-environment` and +`uv pip install` fails with `No virtual environment found`. + +```bash +uv venv --python 3.11 --seed .venv +source .venv/bin/activate +``` + +`--seed` adds pip, so plain `pip install` also works in the venv. To use an existing +venv, or a conda environment other than `base`, activate it and skip `uv venv`. +Activate the environment again in every new terminal. + +## 2. Choose extras + +Extras add optional dependencies. Pick the ones the project needs: + +- `cloudxr`: streaming to an XR headset through the CloudXR runtime. The teleop + examples and camera streaming need it. +- `retargeters`: the full retargeting stack (dex-retargeting, PyTorch, Pinocchio), + for dexterous-hand and joint-space retargeters. +- `retargeters-lite`: SciPy only, enough for lightweight retargeters such as + `Se3AbsRetargeter`. +- `ui`: the imgui parameter-tuning UI. +- `grounding`: the runtime stack of the Sharpa hand retargeter. +- `wuji`: the Wuji glove retargeter. + +The Quick Start installs `cloudxr,retargeters`, which suits teleoperation with an XR +headset. + +## 3. Install + +The latest stable 1.x release: + +```bash +uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' +``` + +Pre-releases are published on the NVIDIA index and need an opt-in: + +```bash +uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' \ + --extra-index-url https://pypi.nvidia.com --prerelease=allow +``` + +To match one version of the documentation exactly, use the pin its Quick Start shows. + +## 4. Check the install + +```bash +python -c "import isaaccapture; print(isaaccapture.__version__)" +``` + +Success prints the installed version number. Anything else is a failed install: + +- `0+unknown`: the import found an `isaaccapture` tree with no installed + distribution, such as a build directory on `PYTHONPATH`. Install the package and + run from outside that tree. +- An `ImportError` saying the legacy `isaacteleop` distribution is still installed: + rerun the install with `--upgrade`, keeping the same version and extras, to + replace it. +- `ModuleNotFoundError: No module named 'isaaccapture'`: the virtual environment + is not active, or the package went into a different environment. + +## References + +- [Quick Start](https://nvidia.github.io/IsaacCapture/main/teleop/quick_start.md) +- [System requirements](https://nvidia.github.io/IsaacCapture/main/references/requirements.md) +- [Retargeting](https://nvidia.github.io/IsaacCapture/main/references/retargeting/index.md) From 89510f5545d3abb67acf9a834cab1b53a57d5f4d Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 27 Oct 2026 16:45:52 +0000 Subject: [PATCH 03/15] docs: add repo-root llms.txt One entry point for agents: what Isaac Capture is, the install skill, the skills index and the main docs pages as Markdown. Skill links are relative so they also resolve inside the wheel. Signed-off-by: Jakob Bornecrantz --- REUSE.toml | 2 +- llms.txt | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 llms.txt diff --git a/REUSE.toml b/REUSE.toml index 754b83e07f..b0a70af9a4 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -32,7 +32,7 @@ SPDX-License-Identifier = "Apache-2.0" # llms.txt files stay plain Markdown for agents, so their REUSE info lives here. [[annotations]] -path = "docs/llms.txt" +path = ["llms.txt", "docs/llms.txt"] precedence = "override" SPDX-FileCopyrightText = "Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved." SPDX-License-Identifier = "Apache-2.0" diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000000..b155473112 --- /dev/null +++ b/llms.txt @@ -0,0 +1,25 @@ +# Isaac Capture + +> Shared capture infrastructure for teleoperation and egocentric data. Isaac Teleop is the robot-in-the-loop component: teleoperation sessions for controlling robots and collecting demonstrations. The Ego Pipeline captures and post-processes egocentric human data. Both build on a shared core of device plugins, retargeters, and data utilities for recording, replaying, and converting data. + +Isaac Capture installs as the `isaaccapture` Python package from PyPI. Skill links are relative to this file. Docs links point at the Markdown copy of each page of the `main` documentation. + +## Install + +- [isaac-capture-install](skills/isaac-capture-install/SKILL.md): skill that creates a uv virtual environment, chooses extras, installs from PyPI, and checks the import +- [Quick Start](https://nvidia.github.io/IsaacCapture/main/teleop/quick_start.md): installation, headset setup, and a first teleoperation session with CloudXR + +## Skills + +- [Skills index](skills/README.md): every Isaac Capture skill and what it covers +- [rebot-orin-setup](https://github.com/NVIDIA/IsaacCapture/blob/main/examples/rebot/SKILL.md): bring up a reBot B601-RS arm from a Jetson AGX Orin over its built-in CAN + +## Docs + +- [Architecture](https://nvidia.github.io/IsaacCapture/main/overview/architecture.md): components, shared infrastructure, and integration environments +- [Teleop Session](https://nvidia.github.io/IsaacCapture/main/teleop/teleop_session.md): the declarative, configuration-based API for setting up complete teleop pipelines +- [Add a New Device](https://nvidia.github.io/IsaacCapture/main/device/add_device.md): write a device plugin for hardware that needs its own driver or SDK +- [Device Conformance Testing](https://nvidia.github.io/IsaacCapture/main/conformance/overview.md): check a device that publishes hand poses against what retargeters need +- [Retargeting Interface](https://nvidia.github.io/IsaacCapture/main/references/retargeting/index.md): the graph-based pipeline from source nodes through retargeters to a single action tensor +- [MCAP Recording & Replay](https://nvidia.github.io/IsaacCapture/main/references/mcap_record_replay.md): record live tracking data to MCAP and replay it offline through the same retargeting pipeline +- [Full documentation index](https://nvidia.github.io/IsaacCapture/main/llms.txt): every page of the `main` documentation as Markdown From 9102911f2f3190212b92b51c1d4e3e788dfec6a9 Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 27 Oct 2026 17:05:00 +0000 Subject: [PATCH 04/15] ci: validate llms.txt and skills with check_agent_docs Nothing else fails when a skill is renamed or a docs page moves. The hook rejects dead relative links, docs URLs that name no main page, invalid skill frontmatter, and skills missing from either index. The pre-commit workflow now runs every test_*.py in tests/python/ci. Signed-off-by: Jakob Bornecrantz --- .github/workflows/pre-commit.yaml | 4 +- .pre-commit-config.yaml | 7 + scripts/check_agent_docs.py | 248 +++++++++++++++++++++++ tests/python/ci/test_check_agent_docs.py | 178 ++++++++++++++++ 4 files changed, 435 insertions(+), 2 deletions(-) create mode 100755 scripts/check_agent_docs.py create mode 100644 tests/python/ci/test_check_agent_docs.py diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index 3a7d240795..dd9da3fe77 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.github/workflows/pre-commit.yaml @@ -37,8 +37,8 @@ jobs: - uses: actions/setup-python@v6 with: python-version: "3.12" - - name: Test preview selection - run: python3 -m unittest discover -s tests/python/ci -p test_docs_preview.py -v + - name: Test CI helper scripts + run: python3 -m unittest discover -s tests/python/ci -p 'test_*.py' -v wheel-publication-tests: name: Test wheel publication lookup diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0a46d0b999..344a071273 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -76,3 +76,10 @@ repos: # src/python/, so a package rename cannot leave copy-pasteable examples # that raise ModuleNotFoundError. .rst and .md both carry those. files: ^(docs/source/.*\.rst|(?!.*/(build|_build|\.venv|node_modules)/).*\.md)$ + - id: check-agent-docs + name: Check llms.txt and skills match the tree + entry: python3 scripts/check_agent_docs.py + language: system + pass_filenames: false + # docs/source/ is in the list because moving a page breaks links to it. + files: ^(llms\.txt|docs/llms\.txt|skills/.*|docs/source/.*\.rst)$ diff --git a/scripts/check_agent_docs.py b/scripts/check_agent_docs.py new file mode 100755 index 0000000000..6ad966bccd --- /dev/null +++ b/scripts/check_agent_docs.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Pre-commit hook: the agent indexes and skills must match the tree. + +1. Relative links in llms.txt and skills/README.md name files that exist. +2. Docs-site URLs in llms.txt, docs/llms.txt and skills/ name the Markdown copy of + a page docs/source/ builds on main, or one of main's llms.txt indexes. +3. Every skills//SKILL.md has Agent Skills frontmatter: a valid name that + matches its directory, and a description. +4. Every skill is linked from both skills/README.md and llms.txt. +""" + +from __future__ import annotations + +import argparse +import re +import subprocess +import sys +from pathlib import Path + +DOCS_SITE = "https://nvidia.github.io/IsaacCapture/" +DOCS_SOURCE = "docs/source" +SKILLS = "skills" +SKILLS_INDEX = "skills/README.md" +REPO_INDEX = "llms.txt" +SITE_INDEX = "docs/llms.txt" + +# Inline Markdown link targets, which in these files never hold whitespace or ")". +LINK_RE = re.compile(r"\]\(([^)\s]+)\)") +# Every docs-site URL, linked or bare, so prose cannot carry a dead one either. +DOCS_URL_RE = re.compile(re.escape(DOCS_SITE) + r"[^\s)\]>\"'`]*") +# https://agentskills.io/specification +NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$") +NAME_MAX = 64 +DESCRIPTION_MAX = 1024 + + +def _repo_root() -> Path: + """Return the work tree root, so the hook can run from any subdirectory.""" + proc = subprocess.run( + ["git", "rev-parse", "--show-toplevel"], + capture_output=True, + text=True, + check=True, + ) + return Path(proc.stdout.strip()) + + +def _read(path: Path) -> str | None: + try: + return path.read_text(encoding="utf-8") + except OSError: + return None + + +def _line(text: str, offset: int) -> int: + return text.count("\n", 0, offset) + 1 + + +def _local_links(root: Path, rel: str) -> tuple[list[str], set[Path]]: + """Return problems with rel's relative links, and the files they resolve to.""" + text = _read(root / rel) + if text is None: + return [], set() + problems: list[str] = [] + targets: set[Path] = set() + for match in LINK_RE.finditer(text): + target = match.group(1) + if "://" in target or target.startswith(("#", "mailto:")): + continue + where = f"{rel}:{_line(text, match.start())}" + resolved = ((root / rel).parent / target.split("#", 1)[0]).resolve() + if not resolved.is_relative_to(root.resolve()): + problems.append(f"{where}: `{target}` resolves outside the repository") + elif not resolved.exists(): + problems.append(f"{where}: `{target}` does not exist") + else: + targets.add(resolved) + return problems, targets + + +def _docs_url_problem(root: Path, url: str) -> str | None: + """Return why url names nothing the main docs publish, or None if it does.""" + rest = url[len(DOCS_SITE) :].split("#", 1)[0] + if rest == "llms.txt": + return None + page = rest.removeprefix("main/") + if page == rest: + return "is not under main/, the only version that publishes Markdown" + source = root / DOCS_SOURCE + if page == "llms.txt": + return None + if page.endswith("/llms.txt"): + section = page.removesuffix("/llms.txt") + if (source / section).is_dir(): + return None + return f"names an index for {DOCS_SOURCE}/{section}/, which does not exist" + if page.endswith(".md"): + if (source / page).with_suffix(".rst").is_file(): + return None + return f"names no page: {DOCS_SOURCE}/{page.removesuffix('.md')}.rst does not exist" + return "is not a page's Markdown copy; link main/.md or an llms.txt" + + +def _docs_links(root: Path, path: Path) -> list[str]: + """Return one problem per docs-site URL in path that names nothing.""" + text = _read(path) + if text is None: + return [] + rel = path.relative_to(root) + problems: list[str] = [] + for match in DOCS_URL_RE.finditer(text): + url = match.group(0).rstrip(".,;:") + reason = _docs_url_problem(root, url) + if reason: + problems.append(f"{rel}:{_line(text, match.start())}: {url} {reason}") + return problems + + +def _frontmatter(text: str) -> dict[str, str] | None: + """Return the top-level scalars of text's leading YAML frontmatter. + + Covers what skills use: plain, quoted and block (``>``, ``|``) scalars. A nested + mapping reads as an empty string; None means there is no frontmatter block. + """ + lines = text.splitlines() + if not lines or lines[0].strip() != "---": + return None + end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None) + if end is None: + return None + body = lines[1:end] + fields: dict[str, str] = {} + index = 0 + while index < len(body): + line = body[index] + index += 1 + if not line.strip() or line[:1].isspace() or line.startswith("#"): + continue + key, separator, value = line.partition(":") + if not separator: + continue + continuation: list[str] = [] + while index < len(body) and ( + not body[index].strip() or body[index][:1].isspace() + ): + continuation.append(body[index].strip()) + index += 1 + parts = [part for part in continuation if part] + value = value.strip() + if value[:1] in (">", "|"): + value = (" " if value[0] == ">" else "\n").join(parts) + elif len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"": + value = value[1:-1] + elif value: + value = " ".join([value, *parts]) + fields[key.strip()] = value + return fields + + +def _skill_problems(root: Path, skill: Path) -> list[str]: + """Return one problem per way skill's SKILL.md breaks the Agent Skills format.""" + rel = skill.relative_to(root).as_posix() + text = _read(skill / "SKILL.md") + if text is None: + return [f"{rel}/: has no SKILL.md"] + where = f"{rel}/SKILL.md:1" + fields = _frontmatter(text) + if fields is None: + return [f"{where}: has no YAML frontmatter between '---' lines"] + problems: list[str] = [] + name = fields.get("name", "") + if not name: + problems.append(f"{where}: frontmatter has no name") + else: + if name != skill.name: + problems.append( + f"{where}: name {name!r} does not match its directory {skill.name!r}" + ) + if not NAME_RE.fullmatch(name): + problems.append( + f"{where}: name {name!r} must be lowercase letters and digits " + "joined by single hyphens" + ) + if len(name) > NAME_MAX: + problems.append( + f"{where}: name is {len(name)} characters; the limit is {NAME_MAX}" + ) + description = fields.get("description", "") + if not description: + problems.append(f"{where}: frontmatter has no description") + elif len(description) > DESCRIPTION_MAX: + problems.append( + f"{where}: description is {len(description)} characters; " + f"the limit is {DESCRIPTION_MAX}" + ) + return problems + + +def check(root: Path) -> list[str]: + """Return one message per problem in the agent indexes and skills under root.""" + problems: list[str] = [] + linked: dict[str, set[Path]] = {} + for index in (REPO_INDEX, SKILLS_INDEX): + found, linked[index] = _local_links(root, index) + problems += found + + skills_dir = root / SKILLS + for path in ( + root / REPO_INDEX, + root / SITE_INDEX, + *sorted(skills_dir.rglob("*.md")), + ): + problems += _docs_links(root, path) + + skills = ( + sorted( + p for p in skills_dir.iterdir() if p.is_dir() and not p.name.startswith(".") + ) + if skills_dir.is_dir() + else [] + ) + for skill in skills: + problems += _skill_problems(root, skill) + wanted = (skill / "SKILL.md").resolve() + for index, targets in linked.items(): + if wanted not in targets: + problems.append( + f"{skill.relative_to(root).as_posix()}/: not linked from {index}" + ) + return problems + + +def main(argv: list[str]) -> int: + parser = argparse.ArgumentParser(description="Check llms.txt and skills/.") + parser.parse_args(argv) + problems = check(_repo_root()) + if problems: + print("The agent indexes or skills do not match the tree.", file=sys.stderr) + for problem in problems: + print(f" {problem}", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/tests/python/ci/test_check_agent_docs.py b/tests/python/ci/test_check_agent_docs.py new file mode 100644 index 0000000000..6d2dd6a3d2 --- /dev/null +++ b/tests/python/ci/test_check_agent_docs.py @@ -0,0 +1,178 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +import importlib.util +import sys +import tempfile +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) +from repo_paths import repo_root + +spec = importlib.util.spec_from_file_location( + "check_agent_docs", repo_root() / "scripts/check_agent_docs.py" +) +agent_docs = importlib.util.module_from_spec(spec) +spec.loader.exec_module(agent_docs) + +SITE = "https://nvidia.github.io/IsaacCapture/main" + + +class CheckAgentDocsTests(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.root = Path(tmp.name) + self.write("docs/source/teleop/quick_start.rst", "Quick Start\n") + self.write("docs/source/device/index.rst", "Devices\n") + self.write("docs/llms.txt", f"- [Docs]({SITE}/llms.txt)\n") + self.write("skills/README.md", "# Skills\n\n") + self.write( + "llms.txt", f"# Demo\n\n- [Quick Start]({SITE}/teleop/quick_start.md)\n" + ) + self.add_skill( + "demo-skill", "name: demo-skill\ndescription: Use when testing.\n" + ) + + def write(self, rel, text): + path = self.root / rel + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + + def append(self, rel, text): + path = self.root / rel + path.write_text(path.read_text(encoding="utf-8") + text, encoding="utf-8") + + def add_skill(self, directory, frontmatter, *, readme=True, llms=True): + self.write( + f"skills/{directory}/SKILL.md", f"---\n{frontmatter}---\n\n# Skill\n" + ) + if readme: + self.append("skills/README.md", f"- [{directory}]({directory}/SKILL.md)\n") + if llms: + self.append("llms.txt", f"- [{directory}](skills/{directory}/SKILL.md)\n") + + def assert_one_problem(self, *fragments): + problems = agent_docs.check(self.root) + self.assertEqual(len(problems), 1, problems) + for fragment in fragments: + self.assertIn(fragment, problems[0]) + + def test_consistent_tree_passes(self): + self.assertEqual(agent_docs.check(self.root), []) + + def test_repository_passes(self): + self.assertEqual(agent_docs.check(repo_root()), []) + + def test_relative_link_must_exist(self): + self.append("llms.txt", "- [Gone](skills/gone/SKILL.md)\n") + self.assert_one_problem("llms.txt:", "`skills/gone/SKILL.md` does not exist") + + def test_relative_link_must_stay_in_the_repository(self): + self.append("skills/README.md", "- [Out](../../outside.md)\n") + self.assert_one_problem("skills/README.md:", "resolves outside the repository") + + def test_anchors_and_external_urls_are_not_paths(self): + self.append("llms.txt", "- [Top](#demo)\n- [GitHub](https://github.com/x/y)\n") + self.assertEqual(agent_docs.check(self.root), []) + + def test_docs_link_must_be_a_markdown_copy(self): + self.append("llms.txt", f"- [HTML]({SITE}/teleop/quick_start.html)\n") + self.assert_one_problem("quick_start.html", "is not a page's Markdown copy") + + def test_docs_link_must_name_a_built_page(self): + self.append("llms.txt", f"- [Gone]({SITE}/teleop/gone.md)\n") + self.assert_one_problem("docs/source/teleop/gone.rst does not exist") + + def test_docs_link_must_point_at_main(self): + url = ( + "https://nvidia.github.io/IsaacCapture/release/1.7.x/teleop/quick_start.md" + ) + self.append("llms.txt", f"- [Old]({url})\n") + self.assert_one_problem("is not under main/") + + def test_section_index_needs_the_section(self): + self.append("llms.txt", f"- [Devices]({SITE}/device/llms.txt)\n") + self.assertEqual(agent_docs.check(self.root), []) + self.append("llms.txt", f"- [Nope]({SITE}/nope/llms.txt)\n") + self.assert_one_problem("docs/source/nope/, which does not exist") + + def test_bare_docs_urls_in_skills_are_checked(self): + self.append( + "skills/demo-skill/SKILL.md", f"\nSee {SITE}/teleop/quick_start.md.\n" + ) + self.assertEqual(agent_docs.check(self.root), []) + self.append("skills/demo-skill/SKILL.md", f"Or {SITE}/teleop/missing.md\n") + self.assert_one_problem("skills/demo-skill/SKILL.md:", "missing.rst") + + def test_site_index_is_checked(self): + self.append("docs/llms.txt", f"- [Gone]({SITE}/gone.md)\n") + self.assert_one_problem("docs/llms.txt:", "gone.rst does not exist") + + def test_name_must_match_the_directory(self): + self.add_skill("other-skill", "name: another-skill\ndescription: Testing.\n") + self.assert_one_problem( + "other-skill/SKILL.md:1", "does not match its directory" + ) + + def test_name_format(self): + self.add_skill("Bad--Name", "name: Bad--Name\ndescription: Testing.\n") + self.assert_one_problem("Bad--Name", "lowercase letters and digits") + + def test_name_length(self): + name = "a" * 65 + self.add_skill(name, f"name: {name}\ndescription: Testing.\n") + self.assert_one_problem("name is 65 characters; the limit is 64") + + def test_description_is_required(self): + self.add_skill("no-description", "name: no-description\n") + self.assert_one_problem("frontmatter has no description") + + def test_description_length(self): + description = "x" * 1025 + self.add_skill( + "long-description", f"name: long-description\ndescription: {description}\n" + ) + self.assert_one_problem("description is 1025 characters; the limit is 1024") + + def test_block_and_quoted_scalars(self): + self.add_skill( + "folded-skill", + "name: 'folded-skill'\ndescription: >-\n Use when the\n value folds.\n" + "metadata:\n internal: true\n", + ) + self.assertEqual(agent_docs.check(self.root), []) + fields = agent_docs._frontmatter( + (self.root / "skills/folded-skill/SKILL.md").read_text(encoding="utf-8") + ) + self.assertEqual(fields["description"], "Use when the value folds.") + self.assertEqual(fields["metadata"], "") + + def test_frontmatter_is_required(self): + self.write("skills/plain-skill/SKILL.md", "# No frontmatter\n") + self.append("skills/README.md", "- [plain-skill](plain-skill/SKILL.md)\n") + self.append("llms.txt", "- [plain-skill](skills/plain-skill/SKILL.md)\n") + self.assert_one_problem("plain-skill/SKILL.md:1", "no YAML frontmatter") + + def test_skill_directory_needs_skill_md(self): + (self.root / "skills/empty-skill").mkdir() + problems = agent_docs.check(self.root) + self.assertIn("skills/empty-skill/: has no SKILL.md", problems) + + def test_skill_must_be_in_both_indexes(self): + self.add_skill( + "unlisted-skill", "name: unlisted-skill\ndescription: x\n", llms=False + ) + self.assert_one_problem("skills/unlisted-skill/: not linked from llms.txt") + self.add_skill( + "hidden-skill", "name: hidden-skill\ndescription: x\n", readme=False + ) + problems = agent_docs.check(self.root) + self.assertIn( + "skills/hidden-skill/: not linked from skills/README.md", problems + ) + + +if __name__ == "__main__": + unittest.main() From b78dd80f5a02b1b35bf4072dabc3256b3a53b1de Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 27 Oct 2026 17:26:40 +0000 Subject: [PATCH 05/15] build(wheel): ship llms.txt and skills in the isaaccapture wheel Projects that install Isaac Capture have the package, not the repo. The wheel now carries isaaccapture/llms.txt and isaaccapture/skills/, side by side so the relative links resolve. test_wheel_contents checks both ship byte for byte. Signed-off-by: Jakob Bornecrantz --- src/core/python/CMakeLists.txt | 4 ++++ src/core/python/pyproject.toml.in | 11 ++++++++++- tests/python/packaging/test_wheel_contents.py | 16 ++++++++++++++++ 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/src/core/python/CMakeLists.txt b/src/core/python/CMakeLists.txt index 6a826f498c..d49739ac75 100644 --- a/src/core/python/CMakeLists.txt +++ b/src/core/python/CMakeLists.txt @@ -78,6 +78,10 @@ add_custom_target(python_package ALL COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/MANIFEST.in" "${CMAKE_BINARY_DIR}/python_package/$/" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/setup.py" "${CMAKE_BINARY_DIR}/python_package/$/" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_SOURCE_DIR}/README.md" "${CMAKE_BINARY_DIR}/python_package/$/README.md" + # llms.txt links skills/ by relative path, so the two ship side by side in the package. + COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_SOURCE_DIR}/llms.txt" "${CMAKE_BINARY_DIR}/python_package/$/isaaccapture/llms.txt" + COMMAND ${CMAKE_COMMAND} -E rm -rf "${CMAKE_BINARY_DIR}/python_package/$/isaaccapture/skills" + COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/skills" "${CMAKE_BINARY_DIR}/python_package/$/isaaccapture/skills" # Remove stale license texts dropped from the list since the last build. COMMAND ${CMAKE_COMMAND} -E rm -rf "${CMAKE_BINARY_DIR}/python_package/$/LICENSES" ${_license_staging_commands} diff --git a/src/core/python/pyproject.toml.in b/src/core/python/pyproject.toml.in index 31ca29b176..d3270a6143 100644 --- a/src/core/python/pyproject.toml.in +++ b/src/core/python/pyproject.toml.in @@ -68,7 +68,16 @@ include = [ [tool.setuptools.package-data] # plugins/: device plugins bundled so wheel installs can start them (BUNDLED_PLUGINS_DIR); not packages. -isaaccapture = ["*.so", "*.pyd", "*.pyi", "py.typed", "plugins/*/*"] +# llms.txt and skills/: the agent index and the skills it links, copied from the repo root. +isaaccapture = [ + "*.so", + "*.pyd", + "*.pyi", + "py.typed", + "plugins/*/*", + "llms.txt", + "skills/**/*", +] "isaaccapture.deviceio" = ["*.so", "*.pyd", "*.pyi"] # CHROMIUM_LICENSE: the notice for the key table compiled into _deviceio_trackers. "isaaccapture.deviceio_trackers" = ["*.so", "*.pyd", "*.pyi", "CHROMIUM_LICENSE"] diff --git a/tests/python/packaging/test_wheel_contents.py b/tests/python/packaging/test_wheel_contents.py index a76c736a61..e0195d4c42 100644 --- a/tests/python/packaging/test_wheel_contents.py +++ b/tests/python/packaging/test_wheel_contents.py @@ -78,6 +78,22 @@ def test_wheel_does_not_ship_cts() -> None: assert shipped == [] +def test_agent_index_and_skills_ship_beside_the_package() -> None: + """llms.txt links skills/ by relative path, so both ship unchanged and side by side.""" + root = repo_root() + expected = {f"{DIST}/llms.txt": root / "llms.txt"} + expected |= { + f"{DIST}/{path.relative_to(root).as_posix()}": path + for path in (root / "skills").rglob("*") + if path.is_file() + } + with zipfile.ZipFile(_wheel()) as archive: + missing = sorted(set(expected) - set(archive.namelist())) + assert not missing, f"missing from the wheel: {missing}" + for name, source in expected.items(): + assert archive.read(name) == source.read_bytes(), f"{name} differs" + + def test_the_shim_ships_beside_the_real_package() -> None: wheel = _wheel() with zipfile.ZipFile(wheel) as archive: From 62879eaea5e91b47b3be34c61be4117882ecdc7c Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:27:39 +0000 Subject: [PATCH 06/15] [FEEDBACK] docs: fix links, images and downloads in the Markdown pages A link inside a parsed-literal block rendered as [url](url), so the pinned install command in teleop/quick_start.md failed in bash. Such links now render as their text. Plain RST section links (`Title`_) rendered as [Title](). They now link #, and markdown_anchor_sections gives every section the anchor they point at. Images and :download: links were relative to the source root rather than the page. They now point at the copies the HTML build serves under _images/ and _downloads/. The HTML output is unchanged. Signed-off-by: Jakob Bornecrantz --- docs/source/_ext/markdown_nodes.py | 65 +++++++++++++++++++++++++++++- docs/source/conf.py | 2 + 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/docs/source/_ext/markdown_nodes.py b/docs/source/_ext/markdown_nodes.py index 72fb96f27c..903bb178cb 100644 --- a/docs/source/_ext/markdown_nodes.py +++ b/docs/source/_ext/markdown_nodes.py @@ -1,17 +1,22 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -"""Markdown for nodes that sphinx-markdown-builder has no visitor for. +"""Markdown for nodes that sphinx-markdown-builder has no visitor for, or gets wrong. That builder drops an unknown node together with its children, so without these the ``page.md`` copies sphinx-llm publishes lose captions, generic admonitions and sphinx-design card titles. Nodes that only matter in HTML are silenced in ``conf.py``. +Its links, images and downloads are also rewritten to resolve from the published page. """ from __future__ import annotations +import posixpath + from docutils import nodes +from sphinx import addnodes from sphinx_design.shared import PassthroughTextElement +from sphinx_markdown_builder.contexts import WrappedContext def _visit_as_paragraph(self, node): @@ -50,6 +55,53 @@ def _depart_card_text(self, node): self.depart_paragraph(node) +def _from_page(self, path): + """``path`` relative to the build root, as a link from the page being written.""" + page_dir = posixpath.dirname(self.builder.current_doc_name) + return posixpath.relpath(path, page_dir or ".") + + +def _parents(node): + parent = node.parent + while parent is not None: + yield parent + parent = parent.parent + + +def _visit_reference(self, node): + """Links in a literal block stay plain text, so a copied command still runs.""" + if any(isinstance(parent, nodes.literal_block) for parent in _parents(node)): + self.add(node.astext()) + raise nodes.SkipNode + # A plain RST link to a section (`Title`_) carries a refid but no "internal" flag, + # which sphinx-markdown-builder reads as an external link with an empty URL. + if node.get("refid") and "refuri" not in node: + self._push_context(WrappedContext("[", f"](#{node['refid']})")) + return + type(self).visit_reference(self, node) + + +def _depart_reference(self, node): + self._pop_context(node) + + +def _visit_image(self, node): + """Point at the copy the HTML build serves, since the Markdown sits beside it.""" + uri = node["uri"] + copied = self.builder.env.images.get(uri) + if copied is not None: + uri = _from_page(self, posixpath.join("_images", copied[1])) + self.add(f"![{node.get('alt', 'image')}]({uri})") + + +def _visit_download_reference(self, node): + if "refuri" in node or "filename" not in node: + type(self).visit_download_reference(self, node) + return + target = _from_page(self, posixpath.join("_downloads", node["filename"])) + self._push_context(WrappedContext("[", f"]({target})")) + + def setup(app): app.add_node( nodes.caption, @@ -62,4 +114,15 @@ def setup(app): override=True, markdown=(_visit_card_text, _depart_card_text), ) + app.add_node( + nodes.reference, + override=True, + markdown=(_visit_reference, _depart_reference), + ) + app.add_node(nodes.image, override=True, markdown=(_visit_image, None)) + app.add_node( + addnodes.download_reference, + override=True, + markdown=(_visit_download_reference, _depart_reference), + ) return {"version": "1.0", "parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/source/conf.py b/docs/source/conf.py index a6ce111e98..7ef06b2a0b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -85,6 +85,8 @@ def _pip_pin(ref_name, fallback): # build too. llms_txt_enabled = _smv_ref_name() in ("", "main") llms_txt_suffix_mode = "replace" +# Anchor every section so in-page links (`Title`_ in RST) resolve in the Markdown. +markdown_anchor_sections = True # A redirect stub's refresh and a hidden toctree mean nothing outside HTML. llms_txt_suppress_unknown_node_warnings = ["meta", "toctree"] # sphinx-llm indexes every *.md in its build, so a :download: of a README.md would be From 7396becf30530adfa569a66c3972d62d4a70b5ff Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:29:17 +0000 Subject: [PATCH 07/15] [FEEDBACK] docs: fail make current-docs on Markdown build warnings sphinx-llm runs its Markdown build without -W and relays only unknown-node warnings, so any other warning there passed CI. When the parent build runs with -W, it now passes that on to the Markdown build as a config override, and the Markdown build exits non-zero on any warning. The parent reports that exit as an error, which -W turns into a failure. Builds without -W keep publishing the Markdown and llms.txt. The hook reads Sphinx's private warning state and raises an ExtensionError if an upgrade removes it, rather than passing silently. Signed-off-by: Jakob Bornecrantz --- docs/source/_ext/markdown_nodes.py | 41 ++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/source/_ext/markdown_nodes.py b/docs/source/_ext/markdown_nodes.py index 903bb178cb..f490d76ba6 100644 --- a/docs/source/_ext/markdown_nodes.py +++ b/docs/source/_ext/markdown_nodes.py @@ -15,9 +15,14 @@ from docutils import nodes from sphinx import addnodes +from sphinx.errors import ExtensionError from sphinx_design.shared import PassthroughTextElement +from sphinx_llm.markdown_builder import SphinxLlmMarkdownBuilder from sphinx_markdown_builder.contexts import WrappedContext +MARKDOWN_BUILDER = SphinxLlmMarkdownBuilder.name +FAIL_ON_WARNINGS = "markdown_fail_on_warnings" + def _visit_as_paragraph(self, node): self.visit_paragraph(node) @@ -102,7 +107,43 @@ def _visit_download_reference(self, node): self._push_context(WrappedContext("[", f"]({target})")) +def _sphinx_private(app, name): + """Read a private Sphinx attribute, failing loudly if an upgrade removed it.""" + try: + return getattr(app, name) + except AttributeError as error: + raise ExtensionError(f"markdown_nodes needs Sphinx.{name}") from error + + +def _forward_fail_on_warnings(app): + """Hand the parent build's -W to the Markdown build sphinx-llm spawns. + + sphinx-llm forwards -D overrides but not -W, and relays only unknown-node warnings. + """ + if app.builder.name != MARKDOWN_BUILDER and _sphinx_private( + app, "_fail_on_warnings" + ): + app.config.overrides[FAIL_ON_WARNINGS] = True + + +def _fail_on_warnings(app, exception): + """A non-zero exit is reported by the parent build as an error, failing its -W. + + Only under -W: on that exit sphinx-llm publishes no Markdown and no llms.txt. + """ + if ( + exception is None + and app.builder.name == MARKDOWN_BUILDER + and app.config[FAIL_ON_WARNINGS] + and _sphinx_private(app, "_warncount") + ): + app.statuscode = 1 + + def setup(app): + app.add_config_value(FAIL_ON_WARNINGS, False, "", bool) + app.connect("builder-inited", _forward_fail_on_warnings) + app.connect("build-finished", _fail_on_warnings) app.add_node( nodes.caption, override=True, From df1b2eaf818c27e858bb6e0f02fe56fadf696236 Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:30:24 +0000 Subject: [PATCH 08/15] [FEEDBACK] docs: leave redirect stubs out of llms.txt A third of the llms.txt entries were redirect stubs whose Markdown only says the page has moved. conf.py now finds every page with a refresh meta tag in the ref being built and adds it to llms_txt_exclude. Their Markdown pages still build, so old links keep resolving. The stub test lives in docs/source/_ext/redirect_stubs.py so that check_agent_docs can share it. Signed-off-by: Jakob Bornecrantz --- docs/source/_ext/redirect_stubs.py | 20 ++++++++++++++++++++ docs/source/conf.py | 19 ++++++++++++++++++- 2 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/source/_ext/redirect_stubs.py diff --git a/docs/source/_ext/redirect_stubs.py b/docs/source/_ext/redirect_stubs.py new file mode 100644 index 0000000000..7b84bde3f7 --- /dev/null +++ b/docs/source/_ext/redirect_stubs.py @@ -0,0 +1,20 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Recognize redirect stubs: pages left at an old URL that refresh to the new one. + +``conf.py`` keeps them out of llms.txt, and ``scripts/check_agent_docs.py`` uses the same +test to know which section indexes sphinx-llm writes. +""" + +from __future__ import annotations + +import re +from pathlib import Path + +_REDIRECT_STUB_RE = re.compile(r"^\.\. meta::\n\s+:http-equiv=refresh:", re.MULTILINE) + + +def is_redirect_stub(path: Path) -> bool: + """Whether the ``.rst`` page at path is a redirect stub.""" + return bool(_REDIRECT_STUB_RE.search(path.read_text(encoding="utf-8"))) diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ef06b2a0b..8328548666 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -90,7 +90,8 @@ def _pip_pin(ref_name, fallback): # A redirect stub's refresh and a hidden toctree mean nothing outside HTML. llms_txt_suppress_unknown_node_warnings = ["meta", "toctree"] # sphinx-llm indexes every *.md in its build, so a :download: of a README.md would be -# listed as a page with no doctree, which -W turns into a failure. +# listed as a page with no doctree, which -W turns into a failure. setup() adds the +# redirect stubs, whose Markdown only says the page has moved. llms_txt_exclude = ["_downloads/**"] # The default is pyproject.toml's description, which still reads "Isaac Teleop". llms_txt_description = ( @@ -328,7 +329,23 @@ def _external_links_new_tab(app, doctree, docname): node["target"] = "_blank" +def _exclude_redirect_stubs(app, config): + """Keep redirect stubs out of llms.txt; their Markdown pages still build.""" + from redirect_stubs import is_redirect_stub + + srcdir = app.srcdir + config.llms_txt_exclude = [ + *config.llms_txt_exclude, + *( + path.relative_to(srcdir).with_suffix("").as_posix() + for path in sorted(srcdir.rglob("*.rst")) + if is_redirect_stub(path) + ), + ] + + def setup(app): + app.connect("config-inited", _exclude_redirect_stubs) app.connect("html-page-context", _versioning_context) app.add_role("code-file", _code_file_role) app.add_role("code-dir", _code_dir_role) From 4648d12b3df1883dc9f82019f4f886951d0093a1 Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:32:19 +0000 Subject: [PATCH 09/15] [FEEDBACK] docs: list the Ecosystem devices in the Markdown build ecosystem.md showed "Supported Devices 14" and no devices, because the Markdown build left the device tables out. The device-matrix directive now also emits a list for that build, one bullet per device with its modes and setup links, and the .. only:: wrappers in ecosystem.rst are gone. The HTML output is unchanged. Signed-off-by: Jakob Bornecrantz --- docs/source/_ext/ecosystem_grid.py | 60 +++++++++++++++++++++++++++--- docs/source/overview/ecosystem.rst | 20 +++------- 2 files changed, 60 insertions(+), 20 deletions(-) diff --git a/docs/source/_ext/ecosystem_grid.py b/docs/source/_ext/ecosystem_grid.py index 0e57c75d75..3ac45449a5 100644 --- a/docs/source/_ext/ecosystem_grid.py +++ b/docs/source/_ext/ecosystem_grid.py @@ -20,11 +20,13 @@ import yaml from docutils import nodes from docutils.parsers.rst import Directive, directives -from sphinx.addnodes import pending_xref +from sphinx.addnodes import only, pending_xref from sphinx.errors import ExtensionError from sphinx.util.docutils import SphinxRole DEVICE_DATA = "_data/devices.yaml" +# The tag sphinx-llm sets on its Markdown build. +MARKDOWN_TAG = "sphinx_llm_markdown" DEVICE_LOGO_DIR = "_static/logos" # A device no release carries yet, so the only way to get it is to build main. @@ -465,8 +467,11 @@ def _device_name(record: dict) -> nodes.paragraph: return line -def _detail_line(entry, docname: str) -> nodes.paragraph: - """One panel entry: a noun phrase, a link, or an address to reach someone at.""" +def _detail_line(entry, docname: str, *, marked: bool = True) -> nodes.paragraph: + """One panel entry: a noun phrase, a link, or an address to reach someone at. + + ``marked=False`` leaves off the external marker, which is HTML-only markup. + """ line = _line(["device-panel-line"]) if isinstance(entry, str): line += nodes.Text(entry) @@ -482,7 +487,7 @@ def _detail_line(entry, docname: str) -> nodes.paragraph: line += nodes.reference("", phone, refuri=f"tel:{_TEL_RE.sub('', phone)}") elif entry.get("url"): ref = nodes.reference("", entry["label"], refuri=entry["url"]) - if _is_external(entry["url"]): + if marked and _is_external(entry["url"]): _mark_external(ref) line += ref else: @@ -666,8 +671,47 @@ def _matrix( return wrapper +def _device_list( + devices: list[dict], planned: list[dict], docname: str, section: str +) -> list[nodes.Node]: + """The Markdown build's form of a section: one bullet per device, setup links included.""" + groups = DEVICE_SECTIONS[section]["groups"] + result: list[nodes.Node] = [] + for group in groups: + rows = [record for record in devices if record["group"] == group] + if not rows: + continue + if len(groups) > 1: + result.append(nodes.rubric("", DEVICE_GROUPS[group])) + bullets = nodes.bullet_list() + for record in rows: + line = _line([]) + line += nodes.reference("", record["name"], refuri=record["url"]) + line += nodes.Text(f": {record['modes']}") + setup = (record.get("details") or {}).get("setup") or [] + for index, entry in enumerate(setup): + line += nodes.Text(". Set up: " if index == 0 else "; ") + line += _detail_line(entry, docname, marked=False).children + bullets += nodes.list_item("", line) + result.append(bullets) + if DEVICE_SECTIONS[section]["planned"] and planned: + bullets = nodes.bullet_list() + for record in planned: + line = _line([], "Planned: ") + line += nodes.reference("", record["name"], refuri=record["url"]) + line += nodes.Text(f" — {record['note']} (") + line += nodes.reference("", "tracking", refuri=record["tracking"]) + line += nodes.Text(")") + bullets += nodes.list_item("", line) + result.append(bullets) + return result + + class DeviceMatrix(Directive): - """Render one section of ``devices.yaml`` as a table: name, value, Details panel.""" + """Render one section of ``devices.yaml`` as a table: name, value, Details panel. + + The table is HTML layout, so the Markdown build for agents gets a list instead. + """ has_content = False option_spec: ClassVar[dict] = { @@ -679,7 +723,11 @@ def run(self) -> list[nodes.Node]: env = self.state.document.settings.env section = self.options.get("section", "input") devices, planned = _load_devices(env, self.options.get("data", DEVICE_DATA)) - return [_matrix(devices, planned, env.docname, section)] + table = only(expr=f"not {MARKDOWN_TAG}") + table += _matrix(devices, planned, env.docname, section) + listing = only(expr=MARKDOWN_TAG) + listing += _device_list(devices, planned, env.docname, section) + return [table, listing] class EcoBlock(Directive): diff --git a/docs/source/overview/ecosystem.rst b/docs/source/overview/ecosystem.rst index c949d20bb6..f2d9de394e 100644 --- a/docs/source/overview/ecosystem.rst +++ b/docs/source/overview/ecosystem.rst @@ -29,12 +29,8 @@ A standardized device interface removes custom integrations and their maintenanc modes determine which retargeters and control schemes are available. :doc:`Add a new device → ` -.. The device tables are interactive HTML layout; the Markdown build for agents leaves them out. - -.. only:: not sphinx_llm_markdown - - .. device-matrix:: - :section: input +.. device-matrix:: + :section: input .. _data-factory: @@ -46,10 +42,8 @@ Data Factory :device-count:`data_factory` Frameworks and services for collecting teleoperation data and turning it into training datasets. -.. only:: not sphinx_llm_markdown - - .. device-matrix:: - :section: data_factory +.. device-matrix:: + :section: data_factory .. _cloud-infrastructure: @@ -60,10 +54,8 @@ Cloud Infrastructure :device-count:`cloud` Cloud platforms available for running Isaac Capture workloads. -.. only:: not sphinx_llm_markdown - - .. device-matrix:: - :section: cloud +.. device-matrix:: + :section: cloud .. rst-class:: eco-section From 52e3c0648b6ba8f5f00d17fdfe4cdf6965a124c9 Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:36:04 +0000 Subject: [PATCH 10/15] [FEEDBACK] docs: opt into pre-releases for isaaccapture alone --prerelease=allow applies to every dependency, so a pre-release install also pulled in lxml 7.0.0b1 and sympy 1.15.0rc2. The pre-release commands in the install skill, the Quick Start and the LeRobot real-robot page now use a specifier that names a pre-release (~=1.0a0, and ~=X.Y.0a0 for the documented series) without the flag. uv and pip then take a pre-release for isaaccapture alone. Checked with uv: it still resolves 1.8.48a1 from the NVIDIA index, with stable lxml and sympy. Signed-off-by: Jakob Bornecrantz --- docs/source/conf.py | 10 ++++++---- .../integrations/lerobot/data_collection_real.rst | 2 +- docs/source/teleop/quick_start.rst | 9 +++++---- skills/isaac-capture-install/SKILL.md | 8 +++++--- 4 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8328548666..97b89ccaca 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,17 +44,19 @@ def _smv_ref_name(): def _pip_pin(ref_name, fallback): - """Install specifier for the series a build describes: ``1.5.x`` -> ``~=1.5.0``. + """Install specifier for the series a build describes: ``1.5.x`` -> ``~=1.5.0a0``. Release refs name their own series (``release/1.4.x``, ``v1.4.7``); ``main`` - and plain ``sphinx-build`` fall back to the checked-out ``VERSION``. + and plain ``sphinx-build`` fall back to the checked-out ``VERSION``. Naming a + pre-release lets pip and uv pick one for isaaccapture alone, where + ``--prerelease=allow`` would extend that to every dependency. """ tail = ref_name.rsplit("/", 1)[-1].removeprefix("v") major, _, rest = (tail if tail[:1].isdigit() else fallback).partition(".") minor = rest.partition(".")[0] if not (major.isdigit() and minor.isdigit()) or major == "0": - return "~=1.0" - return f"~={major}.{minor}.0" + return "~=1.0a0" + return f"~={major}.{minor}.0a0" _pip_version_pin = _pip_pin(_smv_ref_name(), version) diff --git a/docs/source/integrations/lerobot/data_collection_real.rst b/docs/source/integrations/lerobot/data_collection_real.rst index 3f9c9f4c42..a3dc60d038 100644 --- a/docs/source/integrations/lerobot/data_collection_real.rst +++ b/docs/source/integrations/lerobot/data_collection_real.rst @@ -46,7 +46,7 @@ Follow the necessary one-time steps to set up your environment and hardware: source .venv/bin/activate uv pip install -e ".[feetech,kinematics,dataset]" "huggingface_hub>=1.5" uv pip install "isaaccapture[cloudxr,retargeters-lite]\ |pip_version_pin|\ " "scipy>=1.14" \\ - --extra-index-url https://pypi.nvidia.com --prerelease=allow + --extra-index-url https://pypi.nvidia.com The upstream ``isaac_teleop_to_so101`` scripts still import ``isaacteleop``. Installing ``isaaccapture`` includes that compatibility alias automatically diff --git a/docs/source/teleop/quick_start.rst b/docs/source/teleop/quick_start.rst index ced7680813..9d7f41bd81 100644 --- a/docs/source/teleop/quick_start.rst +++ b/docs/source/teleop/quick_start.rst @@ -66,12 +66,13 @@ Install the latest stable release from PyPI: uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' Pre-release builds are published between stable releases. Picking one up takes the NVIDIA index -and an opt-in to pre-release versions: +and a version specifier that names a pre-release, which opts in ``isaaccapture`` alone rather +than every dependency: .. code-block:: bash - uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' \ - --extra-index-url https://pypi.nvidia.com --prerelease=allow + uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0a0' \ + --extra-index-url https://pypi.nvidia.com The two commands above track the newest 1.x release. To follow this version of the documentation (|version|) exactly, pin to the series it describes instead: @@ -79,7 +80,7 @@ The two commands above track the newest 1.x release. To follow this version of t .. parsed-literal:: uv pip install 'isaaccapture[cloudxr,retargeters]\ |pip_version_pin|\ ' \\ - --extra-index-url https://pypi.nvidia.com --prerelease=allow + --extra-index-url https://pypi.nvidia.com Instead of installing the package from PyPI, you can build from source and install the local wheel. See :doc:`../development/build_from_source/index` for more details. diff --git a/skills/isaac-capture-install/SKILL.md b/skills/isaac-capture-install/SKILL.md index 51c41048be..694018ebac 100644 --- a/skills/isaac-capture-install/SKILL.md +++ b/skills/isaac-capture-install/SKILL.md @@ -59,11 +59,13 @@ The latest stable 1.x release: uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' ``` -Pre-releases are published on the NVIDIA index and need an opt-in: +Pre-releases are published on the NVIDIA index. The `a0` in the specifier opts in +`isaaccapture` alone; do not add `--prerelease=allow`, which also takes pre-releases +of every dependency: ```bash -uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' \ - --extra-index-url https://pypi.nvidia.com --prerelease=allow +uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0a0' \ + --extra-index-url https://pypi.nvidia.com ``` To match one version of the documentation exactly, use the pin its Quick Start shows. From 5df165979449ee24a775485b4393f62321bd72be Mon Sep 17 00:00:00 2001 From: Jakob Bornecrantz Date: Tue, 17 Nov 2026 15:37:25 +0000 Subject: [PATCH 11/15] [FEEDBACK] skills: cover extras, stray imports and version skew Review of the install skill found gaps: - The extras list now includes ovxr and desktop-mirror, and says that a release without them only warns. - The import check also prints isaaccapture.__file__. After an install, a stray tree on PYTHONPATH still imports while __version__ reports the installed distribution, so the version alone does not catch it. - The co-installed isaacteleop 1!x distribution is the code-free transition package that replaces the legacy one, so agents no longer mistake it for the legacy package and remove it. - The skill and llms.txt say that the docs track main, which can be ahead of the latest stable release on PyPI. Signed-off-by: Jakob Bornecrantz --- llms.txt | 2 +- skills/isaac-capture-install/SKILL.md | 36 +++++++++++++++++++++------ 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/llms.txt b/llms.txt index b155473112..f8753c8b86 100644 --- a/llms.txt +++ b/llms.txt @@ -2,7 +2,7 @@ > Shared capture infrastructure for teleoperation and egocentric data. Isaac Teleop is the robot-in-the-loop component: teleoperation sessions for controlling robots and collecting demonstrations. The Ego Pipeline captures and post-processes egocentric human data. Both build on a shared core of device plugins, retargeters, and data utilities for recording, replaying, and converting data. -Isaac Capture installs as the `isaaccapture` Python package from PyPI. Skill links are relative to this file. Docs links point at the Markdown copy of each page of the `main` documentation. +Isaac Capture installs as the `isaaccapture` Python package from PyPI. Skill links are relative to this file. Docs links point at the Markdown copy of each page of the `main` documentation, which can describe classes and extras newer than the latest stable release on PyPI; the install skill covers installing a pre-release. ## Install diff --git a/skills/isaac-capture-install/SKILL.md b/skills/isaac-capture-install/SKILL.md index 694018ebac..f7b39e8bae 100644 --- a/skills/isaac-capture-install/SKILL.md +++ b/skills/isaac-capture-install/SKILL.md @@ -3,8 +3,9 @@ name: isaac-capture-install description: >- Use when installing Isaac Capture (the isaaccapture Python package, formerly isaacteleop) into a project: creating a uv virtual environment, choosing extras - (cloudxr, retargeters, retargeters-lite, ui, grounding, wuji), installing a stable - or pre-release build from PyPI, and checking that the install imports. + (cloudxr, retargeters, retargeters-lite, ui, grounding, wuji, ovxr, desktop-mirror), + installing a stable or pre-release build from PyPI, and checking that the install + imports. ---