[DOC] Clarify uv extra synchronization behavior

[mmichelis]

Description

This follow-up to #7096 clarifies how uv handles optional extras across installation, tutorial, overview, and troubleshooting documentation.

The installation guide now explains when to use uv run --extra versus uv sync --inexact --extra, and warns that plain uv sync performs an exact sync that removes packages belonging only to omitted extras. The affected tutorial and overview pages link to this guidance, and troubleshooting now uses uv sync --inexact so it does not remove previously selected extras.

No additional dependencies are required.

Type of change

• Documentation update

Screenshots

Not applicable.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with uv run isaaclab -f
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[isaaclab-review-bot]

Isaac Lab Review Bot

Documentation-only change centralizing uv extra-synchronization guidance under the new installation-uv-extra-sync label and linking relevant installation, tutorial, overview, showroom, and troubleshooting pages to it. The RSL-RL troubleshooting command now preserves previously selected extras with uv sync --inexact.

• Design and architecture: The single-source guidance avoids duplicating exact-versus-inexact synchronization details. The new references remain correctly nested within their surrounding reStructuredText notes and tab items, and the target label is defined once.
• API: No source APIs, CLI arguments, dependencies, or public symbols change. The explicit text on each :ref: is appropriate for a label attached to a paragraph rather than a titled section.
• Implementation: The documented behavior is consistent with uv semantics: uv run --extra minimally updates the environment, uv sync --inexact --extra preserves unrelated installed packages, and plain exact uv sync can remove packages belonging only to omitted extras. The troubleshooting update follows that guidance. The showroom link is slightly broader than its immediate uv run example but remains relevant and non-blocking.

No blocking issues. No inline issue met the actionable-evidence threshold; the assessment above records the review feedback.

Automated review; human maintainers own approval decisions.

[greptile-apps]

Greptile Summary

The PR clarifies how optional uv extras interact with exact and inexact synchronization.

• Documents when to use uv run --extra and uv sync --inexact --extra.
• Warns that plain uv sync can remove dependencies belonging only to omitted extras.
• Links affected tutorials and overview pages to the centralized guidance.
• Updates RSL-RL troubleshooting to preserve previously selected extras.

Confidence Score: 5/5

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

The new synchronization guidance is consistently referenced from the affected pages, and the added global documentation target is present in the installation guide.

Important Files Changed

Filename	Overview
docs/source/setup/installation/index.rst	Adds the central uv extra-synchronization explanation and a global cross-reference target.
docs/source/refs/troubleshooting.rst	Changes RSL-RL recovery guidance to use inexact synchronization and links to the detailed explanation.
docs/source/overview/showroom.rst	Links the deformables demo’s optional-extra command to the centralized synchronization guidance.
docs/source/overview/environments.rst	Adds synchronization guidance for soft-body task extras.
docs/source/tutorials/00_sim/spawn_prims.rst	Links the tetrahedralization command to the new optional-extra guidance.
docs/source/tutorials/01_assets/run_deformable_object.rst	Links the tutorial’s combined Isaac Sim and tetrahedralization extras to the new guidance.

_{Reviews (1): Last reviewed commit: "Clarify uv extra synchronization guidanc..." | Re-trigger Greptile}

[StafaH]

This is too complicated for the typical user. We don't want them to use uv sync --inexact. Why can't they just use the extra?

[mmichelis]

This is too complicated for the typical user. We don't want them to use uv sync --inexact. Why can't they just use the extra?

@StafaH You mean uv run --extra? Yeah that could be an option as well if we only want to advertise the one-time run commands. Should we not advertise the uv sync --inexact commands at all? I'd be fine with that too! I thought adding uv sync --inexact made sense since that is what I use as well.