Repository navigation
Generate a relations reference page with autodoc - #1641
Conversation
Agents authoring environments assembled each relation's YAML kind, parameters and validation behaviour by reading relations.rst, relations.py and the graph types. Each relation docstring now states what it does, which pre-physics check validates it (or that none does) and its restrictions, in Google-style Validation and Restrictions sections. relations_reference.py parses those docstrings with docstring-parser and renders them with the __init__ signatures into docs/pages/concepts/object_placement/relations_reference.rst: a summary table plus, per relation, parameters with types, defaults and enum options, and a YAML skeleton. A test fails when the page is out of date. docstring-parser is declared in the dev extra; it was already installed through cyclopts. relations.rst and the author-environment skill link to the reference. Signed-off-by: Alex Millane <amillane@nvidia.com>
0fc3050 to
c7c4385
Compare
The relations reference page was generated by a custom script and checked in, with a test to catch it going stale. It is now built by Sphinx autodoc and napoleon from the relation docstrings during the docs build, so nothing generated is committed. docs/_ext/relation_docs.py adds each relation's YAML kind, aliases and arity from the relation registry, and fails the build when a relation lacks a Validation section, leaves a constructor parameter out of Args, or is registered but not documented. Usage sections become Google-style Example sections so they render as code. The docs build now imports isaaclab_arena, so it runs in the Arena container; docs/README.md describes the setup. The CI docs jobs still need to move to the Arena image. The generator, its test and the docstring-parser dependency are removed. The author-environment skill points agents at the relation docstrings. Signed-off-by: Alex Millane <amillane@nvidia.com>
Restore the relation docstrings from main and only add a one-line Validation section to each, the missing Args of the position-limit relations, and remove the Usage examples and the __init__ summaries that repeat the class docstring. Drop the Restrictions sections. Shorten the reference page introduction, describe what napoleon does in conf.py, avoid the word arity in the YAML kind line, trim the Sphinx extension, and revert the author-environment skill change. Signed-off-by: Alex Millane <amillane@nvidia.com>
Signed-off-by: Alex Millane <amillane@nvidia.com>
autodoc imports isaaclab_arena, so the docs must build in the framework environment. Move docs/requirements.txt into a docs extra, locked with the framework's dependencies, and install it in the image so that make html works in any Arena container. Signed-off-by: Alex Millane <amillane@nvidia.com>
Add an autosummary table above the relation entries, box each class with a tinted signature bar, and document PlaceableAsset so the parent type links without a nitpick ignore. Tighten the relation summary lines. Signed-off-by: Alex Millane <amillane@nvidia.com>
autodoc imports isaaclab_arena, so the pre-merge docs job and the gh-pages deploy now run in the Arena image. The deploy follows a successful CI run on main so that the latest image includes the docs extra. Each sphinx-multiversion build imports its own checkout, and the relation coverage check skips versions without a relations reference. Signed-off-by: Alex Millane <amillane@nvidia.com>
Move the Sphinx dependencies from docs/requirements.txt into a docs extra that the Arena image installs. The pre-merge docs job and the gh-pages deploy run in the Arena image, and the deploy follows a successful CI run on main so the latest image includes the docs extra. Signed-off-by: Alex Millane <amillane@nvidia.com>
…matically_generated_api_docs
alexmillane
changed the title
Signed-off-by: Alex Millane <amillane@nvidia.com>
…matically_generated_api_docs
The deploy no longer waits for the whole CI workflow, so failing tests don't block docs updates. The latest image can predate this commit's docs extra, so the job installs it from the lock. Signed-off-by: Alex Millane <amillane@nvidia.com>
…matically_generated_api_docs
Signed-off-by: Alex Millane <amillane@nvidia.com>
…matically_generated_api_docs
…relations.py Add Restrictions sections to the relation docstrings and render them, with Validation, below the parameters. Replace the per-relation list in relations.rst with the reference page, and link ClutterOn settings to its reference entry. The authoring skill now looks up relations in relations.py. Signed-off-by: Alex Millane <amillane@nvidia.com>
 [Low impact] The changes affect the documentation and its build, not relation placement at runtime. Fix the simulator-dependent registry lookup before merging so the new page can build safely. Findings
SummaryAdds a relations reference page built from class and constructor docstrings.
Reviews (1) · Last reviewed commit: "Merge branch 'alex/docs/build_in_arena_c..." · Reviewed by Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![arena-review-bot[bot]](https://avatars.githubusercontent.com/u/195794629?s=60&v=4){kind=small}
🤖 Isaac Lab-Arena Review BotSummaryThis PR adds a Relations Reference page built with autodoc. It has a summary table and one entry per relation. A small Sphinx extension ( On Greptile's comment at Findings🔵 Improvement: isaaclab_arena/relations/relations.py:421: The Validation note for Test Coverage and CI Cost"Build the docs (pre-merge)" was skipped on this commit, and pre-commit is still queued. The VerdictMinor fixes needed |
Signed-off-by: Alex Millane <amillane@nvidia.com>
alexmillane
changed the title
alexmillane
changed the title
Signed-off-by: Alex Millane <amillane@nvidia.com>
Move the docs build inside the Arena container to support incoming auto-generated docs. ## Why this change? - Currently, one cannot `import isaaclab_arena` in the docs-building context - This means we can auto-generate docs code. - A follow-up introduces API docs ([#1641](#1641)). ## What changes? - **Dependencies:** the Sphinx packages move from `docs/requirements.txt` to a `docs` extra in `pyproject.toml`. - **Pre-merge docs job** (`ci.yml`): `build_docs_pre_merge` runs in this run's Arena image. - Docs-only PRs skip the image build, so their docs build in the latest published `main` image. - **Docs deploy** (`gh-pages.yml`): the deploy now runs in the Arena `latest` image. - This `latest` image likely comes from the last image so the job therefore installs the `docs` extra from `uv.lock` before building. ## Validation - Built the docs in a local Arena container that has the `docs` extra. --------- Signed-off-by: Alex Millane <amillane@nvidia.com>
…ly_generated_api_docs Signed-off-by: Alex Millane <amillane@nvidia.com> # Conflicts: # .github/workflows/ci.yml # .github/workflows/gh-pages.yml
Add a API reference page for the relations.
Why this change?
What changes?
autosummarytable of the relations and their one-line summaries.autoclassentry per relation containing their docstring data.relation_docsSphinx extension (docs/_ext/relation_docs.py):ObjectRelationLibraryRegistry, below its summary line.relations.py):custom.css): each autodoc class is shown in a bordered box with a tinted signature bar.Validation