Skip to content

[Docs Overhaul] --extra usage explained, and fixes to commands - #6979

Merged
kellyguo11 merged 12 commits into
isaac-sim:developfrom
StafaH:mh/install_docs_detailed
Aug 8, 2026
Merged

[Docs Overhaul] --extra usage explained, and fixes to commands#6979
kellyguo11 merged 12 commits into
isaac-sim:developfrom
StafaH:mh/install_docs_detailed

Conversation

@StafaH

@StafaH StafaH commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Description

Adds a section for explain --extra usage for uv run, and links it to the install and preset.

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have added a changelog fragment under source/<pkg>/changelog.d/ for every touched package (do not edit CHANGELOG.rst or bump extension.toml — CI handles that)
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

@StafaH
StafaH requested a review from a team August 7, 2026 21:26
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Aug 7, 2026
Signed-off-by: Mustafa H <34825877+StafaH@users.noreply.github.com>
@StafaH StafaH changed the title [Docs Overhaul] [Docs Overhaul] --extra usage explained, and fixes to commands Aug 7, 2026
@greptile-apps

greptile-apps Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR clarifies how to select optional dependencies with uv run, centralizes the available extras and compatibility guidance, and associates physics and visualization choices with their required extras.

  • Replaces combined OV backend examples with focused OV PhysX commands.
  • Adds a reusable optional-extras reference section and links to it from the installation and quickstart pages.
  • Expands quickstart tables with required-extra information.

Confidence Score: 5/5

The documentation-only PR appears safe to merge with no actionable defects identified.

The changed commands, extra names, compatibility guidance, and Sphinx references align with the checked project configuration and documentation structure.

Important Files Changed

Filename Overview
docs/source/setup/installation/index.rst Updates OV PhysX examples and adds a referenced catalog of optional extras and incompatible backend combinations.
docs/source/setup/quickstart.rst Aligns the quickstart command with the OV PhysX-only extra and documents required extras for physics and visualization selectors.

Reviews (1): Last reviewed commit: "Add more detail to install docs for -ext..." | Re-trigger Greptile

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isaac Lab Review Bot

The documentation usefully centralizes uv run --extra guidance and links the quickstart to a shared extras reference, but two inconsistencies need correction: rl-games is presented as an installable package extra despite the page stating it is not included in wheel extras, and the expanded backend table leaves several rows without the required third cell.

  • Design and architecture: Centralizing optional-extra documentation under the new installation-optional-extras target is a sound way to avoid duplicated guidance, and the new cross-references use that structure consistently. The shared section must clearly distinguish source-project extras from published wheel extras.
  • API: The documented placement of uv run --extra, supported selector forms, and alignment of --extra ovphysx with physics=ovphysx are consistent. However, listing rl-games alongside extras installed through uv pip install "isaaclab[<extra>]" or uv add contradicts the existing statement that rl_games is not included in wheel extras and requires separate installation.
  • Implementation: The visualizer table was fully converted to three columns, but the backend table adds a Required extra column without adding a third cell to the Isaac Sim PhysX and renderer rows. The list-table therefore has inconsistent row widths and must be completed so docutils can render it.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

- Both OV backends: OV PhysX and OV RTX.
* - ``ovphysx`` / ``ovrtx``
- OV PhysX only / OV RTX only.
* - ``rl-games`` / ``sb3`` / ``skrl`` / ``rsl-rl``

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Warning · Implementation — rl-games listed as unavailable wheel extra

This section tells users to install extras via uv pip install "isaaclab[<extra>]" / uv add, yet the same page states a few lines below that "The rl_games package is not included in wheel extras; install it separately when required". Listing rl-games here sends readers to an install command that will not provide the framework. Remove it, or explicitly separate source-project uv run extras from published wheel extras.

Comment thread docs/source/setup/quickstart.rst
@github-actions github-actions Bot added the isaac-lab Related to Isaac Lab team label Aug 8, 2026
@kellyguo11
kellyguo11 force-pushed the mh/install_docs_detailed branch 2 times, most recently from bab4bc9 to 4f23a07 Compare August 8, 2026 05:00
@kellyguo11
kellyguo11 merged commit a6b2b6e into isaac-sim:develop Aug 8, 2026
73 of 75 checks passed
hujc7 added a commit to hujc7/IsaacLab that referenced this pull request Aug 11, 2026
Merging develop kept this branch's [tool.uv].conflicts block, which
"[Docs Overhaul] --extra usage explained, and fixes to commands" (isaac-sim#6979)
had deleted. The merge was textually clean but reverted that decision:
``uv sync --extra isaacsim --extra ov`` failed on this branch while it
succeeds on develop, and the merged comment above ``all`` claimed no
extra was forked while four were.

Keep only the two pairs this branch needs. Isaac Sim and the OV backends
resolve together again, and the contract test that guarded the empty
table now asserts the single remaining fork instead.
@StafaH
StafaH deleted the mh/install_docs_detailed branch August 18, 2026 05:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation infrastructure isaac-lab Related to Isaac Lab team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants