Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/pre-commit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
8 changes: 8 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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)$
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 7 additions & 0 deletions REUSE.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
13 changes: 13 additions & 0 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <branch>` 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:`
Expand Down
1 change: 1 addition & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
9 changes: 9 additions & 0 deletions docs/llms.txt
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
61 changes: 55 additions & 6 deletions docs/source/_ext/ecosystem_grid.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand All @@ -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:
Expand Down Expand Up @@ -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] = {
Expand All @@ -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):
Expand Down Expand Up @@ -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),
Expand Down
169 changes: 169 additions & 0 deletions docs/source/_ext/markdown_nodes.py
Original file line number Diff line number Diff line change
@@ -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}
20 changes: 20 additions & 0 deletions docs/source/_ext/redirect_stubs.py
Original file line number Diff line number Diff line change
@@ -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")))
Loading
Loading