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

# 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](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) 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

<!--
As you go through the checklist above, you can mark something as done by
putting an x character in it

For example,
- [x] I have done this task
- [ ] I have not done this task
-->

---------

Signed-off-by: Mustafa H <34825877+StafaH@users.noreply.github.com>
Co-authored-by: Kelly Guo <kellyg@nvidia.com>

Author: StafaH

.github/workflows/license-check.yaml

@@ -61,11 +61,11 @@ jobs:
         ACCEPT_EULA: Y
         ISAACSIM_ACCEPT_EULA: YES
       run: |
-        uv sync --extra all --extra test
-        # Isaac Sim conflicts with --extra all under uv, so install it imperatively
-        # after the sync. Read the pinned spec from pyproject (single source of truth).
-        ISAACSIM_SPEC=$(.venv/bin/python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['optional-dependencies']['isaacsim'][0])")
-        uv pip install "$ISAACSIM_SPEC"
+        # ``all`` covers every backend (Isaac Sim included), RL library, and visualizer.
+        # ``rlinf`` and ``mimic`` are outside ``all``, so name them to keep them scanned.
+        # No extras conflict, so this is a single resolution -- Isaac Sim no longer needs
+        # an imperative install after the sync.
+        uv sync --extra all --extra test --extra rlinf --extra mimic
         uv pip install pip-licenses pipdeptree \
           -r tools/template/requirements.txt
         # Put the venv on PATH for later steps.

.github/workflows/wheel.yml

@@ -200,4 +200,4 @@ jobs:
             --extra-index-url https://pypi.nvidia.com \
             --index-strategy unsafe-best-match \
             --prerelease=allow \
-            "${wheel}[isaacsim,all]"
+            "${wheel}[all]"

AGENTS.md

@@ -224,7 +224,7 @@ Notes:
 Snake-style `Test_<Filename_Stem_TitleCase>`, mirroring the filename. Each underscore-separated segment is TitleCase. Common acronyms stay uppercase when separate segments. **Do not** use CamelCase here; snake-style is the deliberate convention for these long compound names.
 
 - ✅ `Test_Cli_Install_Core_In_Uvenv_Correctness`
-- ✅ `Test_Uv_Pip_Install_Isaaclab_All_Isaacsim_Trains_Cartpole`
+- ✅ `Test_Uv_Pip_Install_Isaaclab_All_Trains_Cartpole`
 - ❌ `TestCliInstallCoreInUvenvCorrectness`
 
 #### Method naming (strict)

docs/_extensions/isaaclab_docs.py

@@ -216,7 +216,7 @@ def run(self) -> list[nodes.Node]:
         content = f"""\
 .. code-block:: bash
 
-   uv pip install "isaaclab[isaacsim,all]" \\
+   uv pip install "isaaclab[all]" \\
      --overrides "{overrides_url}" \\
      --extra-index-url https://pypi.nvidia.com \\
      --index-strategy unsafe-best-match --prerelease=allow

docs/source/setup/installation/include/pip_extras_note.rst

@@ -1,4 +1,5 @@
 .. note::
 
    The ``isaaclab`` pip wheel bundles all Isaac Lab extensions. Install with
-   ``[isaacsim,all]`` for the full Isaac Sim workflow.
+   ``[all]`` for the full workflow: it carries Isaac Sim, both OV backends, every RL
+   library, and every visualizer.

docs/source/setup/installation/index.rst

@@ -142,9 +142,9 @@ Install ``uv``, clone Isaac Lab, and start a workflow:
          uv run isaaclab train --rl_library rsl_rl \
             --task Isaac-Cartpole-Direct physics=newton_mjwarp
 
-         # Add OV PhysX and OVRTX only when needed
-         uv run --extra ovphysx,ovrtx isaaclab train --rl_library rsl_rl \
-            --task Isaac-Cartpole-Direct physics=newton_mjwarp
+         # OV PhysX backend
+         uv run --extra ovphysx isaaclab train --rl_library rsl_rl \
+            --task Isaac-Cartpole-Direct physics=ovphysx
 
          # Full Isaac Sim support
          uv run --extra isaacsim isaaclab train --rl_library rsl_rl \
@@ -168,9 +168,9 @@ Install ``uv``, clone Isaac Lab, and start a workflow:
          uv run isaaclab train --rl_library rsl_rl \
             --task Isaac-Cartpole-Direct physics=newton_mjwarp
 
-         # Add OV PhysX and OVRTX only when needed
-         uv run --extra ovphysx,ovrtx isaaclab train --rl_library rsl_rl \
-            --task Isaac-Cartpole-Direct physics=newton_mjwarp
+         # OV PhysX backend
+         uv run --extra ovphysx isaaclab train --rl_library rsl_rl \
+            --task Isaac-Cartpole-Direct physics=ovphysx
 
          # Full Isaac Sim support
          uv run --extra isaacsim isaaclab train --rl_library rsl_rl \
@@ -208,9 +208,9 @@ Install ``uv``, clone Isaac Lab, and start a workflow:
          uv run isaaclab train --rl_library rsl_rl ^
             --task Isaac-Cartpole-Direct physics=newton_mjwarp
 
-         :: Add OV PhysX and OVRTX only when needed
-         uv run --extra ovphysx,ovrtx isaaclab train --rl_library rsl_rl ^
-            --task Isaac-Cartpole-Direct physics=newton_mjwarp
+         :: OV PhysX backend
+         uv run --extra ovphysx isaaclab train --rl_library rsl_rl ^
+            --task Isaac-Cartpole-Direct physics=ovphysx
 
          :: Full Isaac Sim support
          uv run --extra isaacsim isaaclab train --rl_library rsl_rl ^
@@ -219,15 +219,22 @@ Install ``uv``, clone Isaac Lab, and start a workflow:
          :: Play a policy
          uv run isaaclab play --rl_library rsl_rl --task Isaac-Cartpole-Direct --viz newton
 
-``uv run`` installs the core dependencies automatically. Add ``--extra <name>``
-before ``isaaclab`` when a command needs an optional integration. Pass a
-comma-separated list to enable several extras, or repeat ``--extra``. For example,
-``--extra ovphysx,ovrtx`` enables both OV backends. Use ``--extra all`` for a
-larger compatible bundle.
+``uv run`` installs the core dependencies automatically. The ``--extra <name>``
+option resolves an optional integration only when that command needs it. Place it
+before ``isaaclab``; for example, ``--extra ov`` installs both ovphysx and ovrtx
+backends. Pass a comma-separated list or repeat ``--extra``. No extras conflict, so
+any combination resolves into one environment, and ``--extra all`` installs every
+backend, RL library, and visualizer at once:
+
+.. code-block:: bash
+
+   uv run --extra all isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct physics=isaacsim_physx
 
-You are now ready to use Isaac Lab. Continue with the :doc:`/source/setup/quickstart`,
-which starts with your first task and introduces the available commands, RL libraries,
-backends, optional extras, and visualizers.
+See :ref:`installation-optional-extras` for the available extras.
+
+Head over to the :doc:`/source/setup/quickstart`, which starts with your first task and
+introduces the available commands, RL libraries, backends, and visualizers.
 
 .. _installation-legacy-installer:
 
@@ -554,6 +561,8 @@ The project workflow records the dependency in ``pyproject.toml`` and updates ``
 when Isaac Lab is part of an application you maintain; use a standalone environment for exploratory
 or temporary work.
 
+.. _installation-optional-extras:
+
 Optional extras
 ~~~~~~~~~~~~~~~
 
@@ -567,27 +576,38 @@ use ``uv pip install "isaaclab[<extra>]"``; for a uv project, use
 
    * - Extra
      - What it installs
-   * - ``all``
-     - RL framework extras for SB3, SKRL, and RSL-RL.
    * - ``isaacsim``
      - Isaac Sim (``isaacsim[all,extscache]`` version |isaacsim_version|) from
        `pypi.nvidia.com <https://pypi.nvidia.com>`__.
-
-For example, use ``isaaclab[all]`` for the RL extras or
-``isaaclab[isaacsim,all]`` for a full Isaac Sim and RL workflow. Combining ``isaacsim`` and
-``all`` requires the checked-in uv override file because Isaac Sim's package pins currently conflict
-with the Newton viewer stack:
+   * - ``ov``
+     - Both OV backends: OV PhysX and OV RTX.
+   * - ``ovphysx`` / ``ovrtx``
+     - OV PhysX only / OV RTX only.
+   * - ``rl-games`` / ``sb3`` / ``skrl`` / ``rsl-rl`` / ``rlinf``
+     - The corresponding RL framework.
+   * - ``rerun`` / ``viser``
+     - The corresponding visualizer.
+   * - ``mimic`` / ``teleop``
+     - Imitation learning / XR teleoperation.
+   * - ``tetrahedralization`` / ``video``
+     - Mesh tetrahedralization / video recording.
+   * - ``leapp``
+     - LEAP model export support.
+   * - ``all``
+     - Every backend, RL library, and visualizer: ``isaacsim``, ``ov``, ``rl-games``,
+       ``sb3``, ``skrl``, ``rsl-rl``, ``rerun``, and ``viser``.
+   * - ``test``
+     - Developer test and documentation tooling.
+
+Extras can be combined freely: none of them conflict, so any set of extras -- including
+the Isaac Sim and OV backend stacks together -- resolves into a single environment.
+Use ``all`` to get every backend, RL library, and visualizer in one flag. The
+specialized extras (``rlinf``, ``mimic``, ``teleop``, ``tetrahedralization``, ``video``,
+``leapp``) and the developer ``test`` tooling are not part of ``all``; request them by
+name.
 
 .. isaaclab-uv-wheel-install::
 
-The combined installation through ``pip`` is unsupported until the conflicting upstream Isaac Sim
-pins are updated. The ``rl_games`` package is not included in wheel extras; install it separately
-when required:
-
-.. code-block:: bash
-
-   pip install "rl-games @ git+https://github.com/isaac-sim/rl_games.git@python3.11" gym standard-distutils
-
 Install the CUDA-enabled PyTorch build appropriate for your system architecture:
 
 .. tab-set::

docs/source/setup/quickstart.rst

@@ -40,19 +40,18 @@ Training outputs, including checkpoints, are written under ``logs/``. Use
 
    ``uv run`` installs core dependencies automatically. When a command needs an
    optional integration, add ``--extra <name>`` before ``isaaclab``. Pass a
-   comma-separated list to enable several extras, or repeat ``--extra``. For example:
+   comma-separated list to enable several extras. For example:
 
    .. code-block:: bash
 
-      uv run --extra ovphysx,ovrtx isaaclab train --rl_library rsl_rl \
+      uv run --extra ovphysx isaaclab train --rl_library rsl_rl \
          --task Isaac-Cartpole-Direct physics=ovphysx
 
    Extras install capabilities; task selectors choose how to use them. For example,
    ``--extra ovphysx`` makes the OV PhysX integration available, while
-   ``physics=ovphysx`` selects it for the task. Common extras include ``rl-games``,
-   ``skrl``, ``sb3``, ``rlinf``, ``ov`` (both OV backends), ``ovphysx``, ``ovrtx``,
-   ``rerun``, ``viser``, and ``video``. Use ``--extra all`` for a larger compatible
-   bundle.
+   ``physics=ovphysx`` selects it for the task. Extras can be combined freely, and
+   ``--extra all`` installs every backend, RL library, and visualizer at once. See
+   :ref:`installation-optional-extras` for the complete list.
 
 
 Choose an RL library
@@ -138,27 +137,36 @@ configuration; use the task help to see the supported selectors:
    uv run isaaclab train --task Isaac-Cartpole-Direct --help
 
 .. list-table::
-   :widths: 28 72
+   :widths: 28 48 24
    :header-rows: 1
 
    * - Selector
      - Backend
+     - Required extra
    * - ``physics=newton_mjwarp``
      - Newton using the MuJoCo-Warp solver. This is a good default for the quickstart.
+     - None
    * - ``physics=newton_kamino``
      - Newton using the Kamino solver. This backend is beta and supports a limited set of tasks.
+     - None
    * - ``physics=ovphysx``
      - OV PhysX.
+     - ``ov`` or ``ovphysx``
    * - ``physics=isaacsim_physx``
      - Isaac Sim PhysX.
+     - ``isaacsim``
    * - ``renderer=newton_renderer``
      - Newton Warp renderer.
+     - None
    * - ``renderer=ovrtx``
      - OV RTX renderer.
+     - ``ov`` or ``ovrtx``
    * - ``renderer=isaacsim_rtx``
      - Isaac Sim RTX renderer.
+     - ``isaacsim``
    * - ``renderer=rtx``
      - Automatic RTX renderer selection.
+     - ``isaacsim`` or ``ovrtx``
 
 Add task-specific options with ``presets=<name>``; for example:
 
@@ -179,23 +187,27 @@ Use ``--viz`` (or ``--visualizer``) to select one or more visualizers during tra
 comma-separated list without spaces, such as ``--viz newton,rerun``.
 
 .. list-table::
-   :widths: 18 82
+   :widths: 18 58 24
    :header-rows: 1
 
    * - Option
      - Use it to
+     - Required extra
    * - ``--viz newton``
      - Open the Newton visualizer.
+     - None
    * - ``--viz rerun``
-     - Stream the task to the Rerun visualizer. Add ``--extra rerun`` before
-       ``isaaclab`` when it is not already installed.
+     - Stream the task to the Rerun visualizer.
+     - ``rerun``
    * - ``--viz viser``
-     - Open the web-based Viser visualizer. Add ``--extra viser`` before
-       ``isaaclab`` when it is not already installed.
+     - Open the web-based Viser visualizer.
+     - ``viser``
    * - ``--viz kit``
      - Open the Kit visualizer when it is available in your environment.
+     - ``isaacsim``
    * - Omit ``--viz`` or use ``--viz none``
      - Run headlessly.
+     - None
 
 For example, view the same task in both the Newton and Rerun visualizers:
 
@@ -208,6 +220,41 @@ See :doc:`/source/overview/core-concepts/visualization` for visualizer setup and
 configuration.
 
 
+Replay a checkpoint
+-------------------
+
+Train Cartpole to create a checkpoint:
+
+.. code-block:: bash
+
+   uv run isaaclab train --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct --num_envs 16 --max_iterations 10 \
+      physics=newton_mjwarp
+
+Then replay the newest checkpoint in the Newton visualizer:
+
+.. code-block:: bash
+
+   uv run isaaclab play --rl_library rsl_rl \
+      --task Isaac-Cartpole-Direct physics=newton_mjwarp \
+      --checkpoint latest --viz newton
+
+Choose a checkpoint with one of the following selectors:
+
+.. list-table::
+   :widths: 38 62
+   :header-rows: 1
+
+   * - Selector
+     - Loads
+   * - ``--checkpoint <path>``
+     - The checkpoint at the specified local path.
+   * - ``--checkpoint best``
+     - The library-specific best or final checkpoint. If none was saved separately, this resolves to ``latest``.
+   * - ``--checkpoint latest``
+     - The highest-step checkpoint from the newest compatible run.
+
+
 Next steps
 ----------
 

pyproject.toml

@@ -100,13 +100,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-# Automatic surface-to-volume tetrahedralization. PyTetWild imports PyVista eagerly,
-# so its ``all`` extra is required even when only the array API is used.
+
 tetrahedralization = ["pytetwild[all]>=0.3.0,<0.4"]
-# Video recording. MoviePy bundles an FFmpeg binary through imageio-ffmpeg, so
-# keep this dependency explicit rather than including it in default installs.
+
 video = ["moviepy>=1.0.3,<2.0.0.dev0"]
-# Developer/test tooling.
+
 test = [
     "pytest",
     "pytest-mock",
@@ -149,7 +147,6 @@ rerun = [
 ]
 
 isaacsim = ["isaacsim[all,extscache]==6.0.1.0"]
-
 ov = ["ovphysx==0.5.9", "ovrtx>=0.4.0,<0.5.0", "ovstage==0.1.0.346039"]
 ovphysx = ["ovphysx==0.5.9", "ovstage==0.1.0.346039"]
 ovrtx = ["ovrtx>=0.4.0,<0.5.0", "ovstage==0.1.0.346039"]
@@ -160,17 +157,13 @@ mimic = [
     "robomimic @ git+https://github.com/ARISE-Initiative/robomimic.git@v0.4.0 ; sys_platform == 'linux'",
 ]
 
-# XR teleoperation: carries Isaac Sim for the Kit XR runtime, and isaaclab_mimic because
-# ``isaaclab teleop record`` imports it (robomimic stays in ``mimic``).
 teleop = [
     "isaacsim[all,extscache]==6.0.1.0",
     "isaaclab-teleop",
     "isaaclab-mimic",
-    # IsaacTeleop is Linux x86_64 only
     "isaacteleop[retargeters,ui,cloudxr]~=1.4.0 ; platform_system == 'Linux' and platform_machine == 'x86_64'",
     "dex-retargeting==0.5.0 ; platform_system == 'Linux' and platform_machine == 'x86_64'",
 ]
-# RLinf VLA post-training (externally contributed).
 rlinf = [
     "ray[default]>=2.47.0",
     "av>=12.3.0",
@@ -183,16 +176,16 @@ rlinf = [
     "peft>=0.17.0",
     "pandas",
 ]
-# Aggregate of the compatible extras. Omits teleop (would pull Isaac Sim in) and ovphysx
-# (packaging<24 clash with isaacsim); install those via their own extra.
-# Also omits tetrahedralization and video because their dependencies are large and
-# narrowly used; request either extra explicitly when needed.
-all = [
-    "isaaclab-dev[sb3,skrl,rl-games,rsl-rl,viser,rerun,rlinf,mimic]",
-]
 leapp = [
     "leapp>=0.5.2",
 ]
+# Every backend, RL library, and visualizer in one flag. No extra is forked in
+# [tool.uv].conflicts, so Isaac Sim and both OV backends resolve into a single
+# environment. The specialized extras (rlinf, mimic, teleop, tetrahedralization,
+# video, leapp) and the developer ``test`` tooling stay opt-in by name.
+all = [
+    "isaaclab-dev[sb3,skrl,rl-games,rsl-rl,viser,rerun,isaacsim,ov]",
+]
 
 # Single source of truth for externally-pinned versions, read by docs/conf.py, the
 # install CLI, and CI. TOML cannot interpolate, so the pins in [project.dependencies],
@@ -406,12 +399,6 @@ override-dependencies = [
     # platform split from [project.dependencies] so only one lands per platform.
     "usd-exchange>=2.2 ; platform_machine == 'aarch64'",
 ]
-# ``ov`` stays forked: it pulls ovrtx, which is not validated alongside Isaac Sim.
-# ``teleop`` bundles isaacsim, so it inherits that pair.
-conflicts = [
-    [{ extra = "teleop" }, { extra = "ov" }],
-    [{ extra = "isaacsim" }, { extra = "ov" }],
-]
 python-preference = "only-managed"
 package = false