diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index 3a7d240795..9a35f192ef 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.github/workflows/pre-commit.yaml @@ -26,7 +26,7 @@ jobs: # Keep small CI helper tests in this workflow, outside local pre-commit hooks. docs-preview-tests: - name: Test docs preview selection + name: Test docs preview selection and agent docs check runs-on: ubuntu-latest permissions: contents: read @@ -37,8 +37,12 @@ jobs: - uses: actions/setup-python@v6 with: python-version: "3.12" + - name: Install test dependencies + run: python3 -m pip install pyyaml==6.0.2 - name: Test preview selection run: python3 -m unittest discover -s tests/python/ci -p test_docs_preview.py -v + - name: Test the agent docs check + run: python3 -m unittest discover -s tests/python/ci -p test_check_agent_docs.py -v wheel-publication-tests: name: Test wheel publication lookup diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0a46d0b999..6c109632c0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -76,3 +76,11 @@ 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: python scripts/check_agent_docs.py + language: python + additional_dependencies: ["pyyaml==6.0.2"] + 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/README.md b/README.md index cd55de9172..69e7a13678 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,10 @@ Our [documentation page](https://nvidia.github.io/IsaacCapture) provides everyth - [How to build from source](https://nvidia.github.io/IsaacCapture/main/getting_started/build_from_source.html) - [OVXR installation](docs/source/getting_started/ovxr.rst) +### Coding Agents + +Point a coding agent at [llms.txt](https://github.com/NVIDIA/IsaacCapture/blob/main/llms.txt), which indexes the install skill and the documentation as Markdown. An installed wheel carries the same file as `isaaccapture/llms.txt` in `site-packages`. + ### Check a Device Integration The CTS records one scripted take from a hand-tracking or full-body device and checks it against the data a retargeter needs; start with the [hand](src/python/isaaccapture/cts/hand/README.md) or [full-body](src/python/isaaccapture/cts/full_body/README.md) guide. diff --git a/REUSE.toml b/REUSE.toml index 38c21963fb..b0a70af9a4 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 = ["llms.txt", "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..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): @@ -750,6 +798,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..f490d76ba6 --- /dev/null +++ b/docs/source/_ext/markdown_nodes.py @@ -0,0 +1,169 @@ +# 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, 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.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) + + +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 _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 _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, + 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), + ) + 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/_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 26c4d3ea6e..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) @@ -68,6 +70,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 +82,27 @@ 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" +# 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 +# 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 = ( + "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) @@ -306,7 +331,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) 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/llms.txt b/llms.txt new file mode 100644 index 0000000000..f8753c8b86 --- /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, which can describe classes and extras newer than the latest stable release on PyPI; the install skill covers installing a pre-release. + +## 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 diff --git a/scripts/check_agent_docs.py b/scripts/check_agent_docs.py new file mode 100755 index 0000000000..9cade8c4f5 --- /dev/null +++ b/scripts/check_agent_docs.py @@ -0,0 +1,266 @@ +#!/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/ name files that exist inside llms.txt or + skills/, the only part of the tree the wheel ships. +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 + +import yaml + +# The docs build's own test, so this check and llms.txt agree on what a stub is. +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "docs/source/_ext")) +from redirect_stubs import is_redirect_stub # noqa: E402 + +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 _ships(root: Path, path: Path) -> bool: + """Whether the wheel ships path, which src/core/python/CMakeLists.txt decides.""" + root = root.resolve() + return path == root / REPO_INDEX or path.is_relative_to(root / SKILLS) + + +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 _ships(root, resolved): + problems.append( + f"{where}: `{target}` is outside {REPO_INDEX} and {SKILLS}/, " + "so it breaks in the wheel; link it by URL" + ) + 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 any(part in ("", ".", "..") for part in page.split("/")): + return "has an empty, '.' or '..' path segment" + if page.endswith("/llms.txt"): + section = page.removesuffix("/llms.txt") + # sphinx-llm indexes a directory with an indexed page at any depth below it, + # and conf.py leaves redirect stubs out of the index. + if any(not is_redirect_stub(p) for p in (source / section).rglob("*.rst")): + return None + return ( + f"names an index for {DOCS_SOURCE}/{section}/, which holds no pages " + "other than redirect stubs" + ) + 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 | None: + """Return text's leading YAML frontmatter, or None if it has no such block. + + Raises ValueError when the block is not YAML or not a mapping. + """ + 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 + try: + fields = yaml.safe_load("\n".join(lines[1:end])) + except yaml.YAMLError as error: + raise ValueError(f"is not valid YAML: {error}") from error + if fields is None: + return {} + if not isinstance(fields, dict): + raise ValueError("is not a mapping") + 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" + try: + fields = _frontmatter(text) + except ValueError as error: + return [f"{where}: frontmatter {error}"] + if fields is None: + return [f"{where}: has no YAML frontmatter between '---' lines"] + problems: list[str] = [] + name = fields.get("name") + description = fields.get("description") + for key, value in (("name", name), ("description", description)): + if value is not None and not isinstance(value, str): + problems.append(f"{where}: {key} must be a string") + if problems: + return problems + 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}" + ) + 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] = [] + skills_dir = root / SKILLS + skill_pages = sorted(skills_dir.rglob("*.md")) + linked: dict[str, set[Path]] = {REPO_INDEX: set(), SKILLS_INDEX: set()} + for rel in ( + REPO_INDEX, + *(path.relative_to(root).as_posix() for path in skill_pages), + ): + found, targets = _local_links(root, rel) + problems += found + if rel in linked: + linked[rel] = targets + + for path in ( + root / REPO_INDEX, + root / SITE_INDEX, + *skill_pages, + ): + 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/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..c82f6dadc4 --- /dev/null +++ b/skills/isaac-capture-install/SKILL.md @@ -0,0 +1,119 @@ +--- +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, ovxr, desktop-mirror), + 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. + +The documentation linked here tracks `main`, which can be ahead of the newest stable +release on PyPI: a class, function or extra it describes may be missing from a stable +install. When the project needs one of those, install a pre-release (step 3). + +## 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. +- `ovxr`: XR presentation through OVXR, for applications that render to a headset. + See [OVXR installation](https://nvidia.github.io/IsaacCapture/main/getting_started/ovxr.md). +- `desktop-mirror`: the OVUI desktop mirror, used together with `ovxr`. It needs + Python 3.12 or newer; on 3.11 it skips OVUI, so the mirror is unavailable. + +Older releases lack `ovxr` and `desktop-mirror`. On a release without them, pip and +uv only warn that the extra does not exist and install the rest. + +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. 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.0a0' \ + --extra-index-url https://pypi.nvidia.com +``` + +To match one version of the documentation exactly, use the pin its Quick Start shows. + +## 4. Check the install + +Run this from outside any Isaac Capture checkout: + +```bash +python -c "import isaaccapture; print(isaaccapture.__version__, isaaccapture.__file__)" +``` + +Success prints the installed version number and a path inside the virtual +environment's `site-packages`. Anything else is a failed install: + +- A path outside `site-packages`: the import found another `isaaccapture` tree, + usually through `PYTHONPATH` or the current directory, and the version printed may + be the installed one rather than that tree's. Unset `PYTHONPATH` or change + directory, then check again. +- `0+unknown`: the same, with a tree that has no installed distribution at all. +- 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. + +`isaaccapture` installs an `isaacteleop` distribution with an epoch-1 version such as +`1!1.6.152` beside itself. That is a transition package with no code that replaces +the legacy one, so leave it installed; old `isaacteleop` imports are served from the +`isaaccapture` package. + +Newer releases ship `llms.txt` and these skills inside the package. The +`llms.txt` beside the `__init__.py` printed above indexes the rest. + +## 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) 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/src/python/isaaccapture/__init__.py b/src/python/isaaccapture/__init__.py index 4a63b9a2d9..9d4b7129b0 100644 --- a/src/python/isaaccapture/__init__.py +++ b/src/python/isaaccapture/__init__.py @@ -4,6 +4,8 @@ """Isaac Teleop - Teleoperation Core Library This package provides Python bindings for teleoperation with Device I/O. + +Coding agents: ``llms.txt`` beside this file indexes the skills and documentation. """ import os 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..9213aa85ce --- /dev/null +++ b/tests/python/ci/test_check_agent_docs.py @@ -0,0 +1,227 @@ +# 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_what_the_wheel_ships(self): + self.write("README.md", "# Repo\n") + self.append("llms.txt", "- [Readme](README.md)\n") + self.assert_one_problem( + "llms.txt:", "`README.md` is outside llms.txt and skills/" + ) + + 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:", "is outside llms.txt and skills/") + + def test_relative_links_in_skills_are_checked(self): + self.append("skills/demo-skill/SKILL.md", "\nSee [the index](../README.md).\n") + self.assertEqual(agent_docs.check(self.root), []) + self.append("skills/demo-skill/SKILL.md", "Or [gone](gone.md).\n") + self.assert_one_problem( + "skills/demo-skill/SKILL.md:", "`gone.md` does not exist" + ) + + 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 holds no pages") + + def test_section_index_needs_pages(self): + self.write("docs/source/_static/logo.svg", "\n") + self.append("llms.txt", f"- [Static]({SITE}/_static/llms.txt)\n") + self.assert_one_problem("docs/source/_static/, which holds no pages") + + def test_section_index_counts_pages_in_subdirectories(self): + self.write("docs/source/guides/lerobot/sim.rst", "Sim\n") + self.append("llms.txt", f"- [Guides]({SITE}/guides/llms.txt)\n") + self.assertEqual(agent_docs.check(self.root), []) + + def test_section_index_ignores_redirect_stubs(self): + stub = ".. meta::\n :http-equiv=refresh: 0; url=../teleop/quick_start.html\n" + self.write("docs/source/old/quick_start.rst", stub + "\nMoved\n") + self.append("llms.txt", f"- [Old]({SITE}/old/llms.txt)\n") + self.assert_one_problem("docs/source/old/", "other than redirect stubs") + + def test_docs_link_must_be_a_normalized_path(self): + self.append("llms.txt", f"- [Up]({SITE}/teleop/../teleop/quick_start.md)\n") + self.assert_one_problem("'..' path segment") + + 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"], {"internal": True}) + + def test_frontmatter_must_be_valid_yaml(self): + self.add_skill("colon-skill", "name: colon-skill\ndescription: Use when: x\n") + self.assert_one_problem( + "colon-skill/SKILL.md:1", "frontmatter is not valid YAML" + ) + + def test_frontmatter_must_be_a_mapping(self): + self.add_skill("list-skill", "- name\n- description\n") + self.assert_one_problem("list-skill/SKILL.md:1", "frontmatter is not a mapping") + + def test_name_must_be_a_string(self): + self.add_skill("number-skill", "name: 42\ndescription: Testing.\n") + self.assert_one_problem("number-skill/SKILL.md:1", "name must be a string") + + 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() 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: