Adds quick installation and supporting doc pages (#5002)

rdsa-nv · AntoineRichard · web-flow · commit 51392035f318 · 2026-03-14T13:11:33.000-07:00
## Summary - Adds a concise **Quick Installation** page (`quick_installation.rst`) with copy-paste install + run steps - Adds `installation_guide.rst`, `configurations.rst`, and `robots.rst` reference pages - Registers all new pages in the Getting Started toctree Split from #4966 per reviewer feedback (docs-only changes). ## Test plan - [ ] Build docs with `./isaaclab.sh -d` and verify new pages render correctly - [ ] Verify toctree links resolve without warnings - [ ] Confirm `quickstart.rst` (upstream) is unchanged --------- Co-authored-by: Antoine Richard <antoiner@nvidia.com>
diff --git a/docs/index.rst b/docs/index.rst
@@ -100,6 +100,7 @@ Table of Contents
    :titlesonly:
 
    source/setup/quickstart
+   source/setup/quick_installation
    source/overview/own-project/index
    source/setup/walkthrough/index
    source/tutorials/index
@@ -148,7 +149,6 @@ Table of Contents
    :caption: Resources
    :titlesonly:
 
-   source/setup/installation/cloud_installation
    source/policy_deployment/index
 
 .. toctree::
diff --git a/docs/source/how-to/index.rst b/docs/source/how-to/index.rst
@@ -24,6 +24,7 @@ how to import a new asset into Isaac Lab.
 
     import_new_asset
     write_articulation_cfg
+    robots
 
 Creating a Fixed Asset
 ----------------------
diff --git a/docs/source/how-to/robots.rst b/docs/source/how-to/robots.rst
@@ -0,0 +1,67 @@
+.. _isaac-lab-robots:
+
+Robot Configurations
+=======================
+
+Robots are entirely defined as instances of configurations within Isaac Lab.  If you examine ``source/isaaclab_assets/isaaclab_assets/robots``, you will see a number of files, each of which
+contains configurations for the robot in question.  The purpose of these individual files is to better define scope for all the different robots, but there is nothing preventing
+you from :ref:`adding your own <tutorial-add-new-robot>` to your project or even to the ``isaaclab`` repository! For example, consider the following configuration for
+the Dofbot
+
+.. code-block:: python
+
+    import isaaclab.sim as sim_utils
+    from isaaclab.actuators import ImplicitActuatorCfg
+    from isaaclab.assets.articulation import ArticulationCfg
+    from isaaclab.utils.assets import ISAAC_NUCLEUS_DIR
+
+    DOFBOT_CONFIG = ArticulationCfg(
+        spawn=sim_utils.UsdFileCfg(
+            usd_path=f"{ISAAC_NUCLEUS_DIR}/Robots/Dofbot/dofbot.usd",
+            rigid_props=sim_utils.RigidBodyPropertiesCfg(
+                disable_gravity=False,
+                max_depenetration_velocity=5.0,
+            ),
+            articulation_props=sim_utils.ArticulationRootPropertiesCfg(
+                enabled_self_collisions=True, solver_position_iteration_count=8, solver_velocity_iteration_count=0
+            ),
+        ),
+        init_state=ArticulationCfg.InitialStateCfg(
+            joint_pos={
+                "joint1": 0.0,
+                "joint2": 0.0,
+                "joint3": 0.0,
+                "joint4": 0.0,
+            },
+            pos=(0.25, -0.25, 0.0),
+        ),
+        actuators={
+            "front_joints": ImplicitActuatorCfg(
+                joint_names_expr=["joint[1-2]"],
+                effort_limit_sim=100.0,
+                velocity_limit_sim=100.0,
+                stiffness=10000.0,
+                damping=100.0,
+            ),
+            "joint3_act": ImplicitActuatorCfg(
+                joint_names_expr=["joint3"],
+                effort_limit_sim=100.0,
+                velocity_limit_sim=100.0,
+                stiffness=10000.0,
+                damping=100.0,
+            ),
+            "joint4_act": ImplicitActuatorCfg(
+                joint_names_expr=["joint4"],
+                effort_limit_sim=100.0,
+                velocity_limit_sim=100.0,
+                stiffness=10000.0,
+                damping=100.0,
+            ),
+        },
+    )
+
+This completely defines the dofbot! You could copy this into a ``.py`` file and import it as a module and you would be able to use the dofbot in
+your own lab sims. One common feature you will see in any config defining things with state is the presence of an ``InitialStateCfg``.  Remember, the configurations
+are what informs vectorization, and it's the ``InitialStateCfg`` that describes the state of the joints of our robot when it gets created in each environment. The
+``ImplicitActuatorCfg`` defines the joints of the robot using the default actuation model determined by the joint type.  Not all joints need to be actuated, but you
+will get warnings if you don't.  If you aren't planning on using those undefined joints, you can generally ignore these.
diff --git a/docs/source/refs/troubleshooting.rst b/docs/source/refs/troubleshooting.rst
@@ -9,6 +9,75 @@ Tricks and Troubleshooting
     assistance.
 
 
+Installation Troubleshooting
+----------------------------
+
+``ModuleNotFoundError: No module named 'pip'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your venv was created without pip. The install system auto-detects and uses
+``uv pip`` when pip is absent, so this error should no longer occur with the
+latest Isaac Lab.
+
+``ModuleNotFoundError: No module named 'isaacsim'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You are running a script that requires Isaac Sim, but it is not installed.
+Either:
+
+- Install Isaac Sim: ``./isaaclab.sh -i isaacsim``, or
+- Use a Newton-based task with ``presets=newton --visualizer newton`` (Kit-less path)
+
+``ModuleNotFoundError: No module named 'isaaclab_physx'`` or ``'isaaclab_ov'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These config packages are auto-installed by ``./isaaclab.sh -i``. If using a
+selective install, re-run with the default ``./isaaclab.sh -i`` to get all
+packages.
+
+``ModuleNotFoundError: No module named 'isaaclab_assets'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Include ``assets`` in your install command, or use ``./isaaclab.sh -i`` to install
+everything.
+
+``ModuleNotFoundError: No module named 'rsl_rl'``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Include the RL framework: ``./isaaclab.sh -i rsl_rl``, or use
+``./isaaclab.sh -i`` to install all frameworks.
+
+Crash in ``libusd_tf`` / USD Symbol Collision with OVRTX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you see a crash involving ``libusd_tf-*.so`` and conflicting USD versions
+(e.g. ``pxrInternal_v0_25_5`` vs ``pxrInternal_v0_25_11``):
+
+1. Ensure ``LD_PRELOAD`` is set to ovrtx's ``libcarb.so`` (see the
+   :ref:`OVRTX section <installation-ovrtx>` of the installation guide)
+2. Ensure ``isaacsim`` / ``omniverse-kit`` is **not** installed in the same
+   environment — their bundled USD libraries conflict with ovrtx's
+
+Visualizer Not Appearing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``--visualizer newton`` shows no window, you may be missing ``imgui-bundle``:
+
+.. code-block:: bash
+
+   uv pip install imgui-bundle
+
+For ``viser``, check the terminal for a URL (e.g. ``http://localhost:8012``).
+
+``GLIBC Version Too Old``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Isaac Sim pip packages require GLIBC 2.35+. Check with ``ldd --version``.
+Ubuntu 22.04+ satisfies this. For older distributions, use the
+`binary installation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html>`_
+method for Isaac Sim.
+
+
 Debugging physics simulation stability issues
 ---------------------------------------------
 
diff --git a/docs/source/setup/installation/index.rst b/docs/source/setup/installation/index.rst
@@ -147,6 +147,13 @@ fastest way to get started and is ideal for users who only need the Newton physi
    # Install Isaac Lab (Newton backend, no Isaac Sim required)
    ./isaaclab.sh --install   # or ./isaaclab.sh -i
 
+   # Kickoff training with Newton physics and Newton visualizer
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+   --task=Isaac-Cartpole-Direct-v0 \
+   --num_envs=16 --max_iterations=10 \
+   presets=newton --visualizer newton
+
+
 **Features available in kit-less mode (Newton backend, no Isaac Sim):**
 
 - Newton physics simulation (GPU-accelerated, including MuJoCo-Warp solver)
@@ -163,11 +170,92 @@ fastest way to get started and is ideal for users who only need the Newton physi
 - ROS / ROS2 integration
 - URDF and MJCF importers (GUI-based)
 - Deformable objects and surface gripper (PhysX-only)
-- Teleoperation and imitiation learning workflows
+- Teleoperation and imitation learning workflows
 
 To install Isaac Sim, use the pip method described in :doc:`pip_installation`.
 
 
+.. _installation-selective-install:
+
+Selective Install
+-----------------
+
+If you want a minimal environment, ``./isaaclab.sh -i`` accepts comma-separated
+sub-package names:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Option
+     - What it does
+   * - ``isaacsim``
+     - Install Isaac Sim pip package
+   * - ``newton``
+     - Install Newton physics + Newton visualizer
+   * - ``physx``
+     - Install PhysX physics runtime
+   * - ``ovrtx``
+     - Install OVRTX renderer runtime
+   * - ``tasks``
+     - Install built-in task environments
+   * - ``assets``
+     - Install robot/object configurations
+   * - ``visualizers``
+     - Install all visualizer backends
+   * - ``rsl_rl``
+     - Install RSL-RL framework
+   * - ``skrl``
+     - Install skrl framework
+   * - ``sb3``
+     - Install Stable Baselines3 framework
+   * - ``rl_games``
+     - Install rl_games framework
+   * - ``robomimic``
+     - Install robomimic framework
+   * - ``none``
+     - Install only core ``isaaclab`` package
+
+Examples:
+
+.. code-block:: bash
+
+   # Minimal Newton setup
+   ./isaaclab.sh -i newton,tasks,assets
+
+   # Newton with OVRTX and RSL-RL only
+   ./isaaclab.sh -i newton,tasks,assets,ovrtx,rsl_rl
+
+   # Full Kit install with skrl
+   ./isaaclab.sh -i isaacsim,skrl
+
+
+.. _installation-ovrtx:
+
+OVRTX Rendering
+---------------
+
+OVRTX provides GPU-accelerated rendering for vision tasks without Kit.
+
+.. code-block:: bash
+
+   ./isaaclab.sh -i ov[ovrtx]
+
+   export LD_PRELOAD=$(python -c "import ovrtx, pathlib; print(pathlib.Path(ovrtx.__file__).parent / 'bin/plugins/libcarb.so')")
+
+   ./isaaclab.sh -p scripts/benchmarks/benchmark_rsl_rl.py \
+     --task Isaac-Repose-Cube-Shadow-Vision-Benchmark-Direct-v0 \
+     --headless --enable_cameras --num_envs 16 --max_iterations 10 \
+     presets=newton,ovrtx_renderer,simple_shading_diffuse_mdl
+
+
+Running Installation Tests
+--------------------------
+
+.. code-block:: bash
+
+   ./isaaclab.sh -p -m pytest source/isaaclab/test/cli/test_cli_utils.py -v
+
+
 Isaac Sim Installation
 ----------------------
 
diff --git a/docs/source/setup/quick_installation.rst b/docs/source/setup/quick_installation.rst
@@ -0,0 +1,86 @@
+.. _isaac-lab-quick-installation:
+
+Quick Installation
+=======================
+
+``./isaaclab.sh -i`` installs everything needed to run with Newton Physics out of the box.
+
+.. code-block:: bash
+
+   # Install uv
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+
+   # Clone Isaac Lab
+   git clone https://github.com/isaac-sim/IsaacLab.git
+   cd IsaacLab
+
+   # Create environment and install
+   uv venv .venv --python 3.12
+   source .venv/bin/activate
+   ./isaaclab.sh -i
+
+   # Run training (Newton backend, 16 envs)
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task=Isaac-Cartpole-Direct-v0 \
+     --num_envs=16 --max_iterations=10 \
+     presets=newton --visualizer newton
+
+
+Running Tasks
+-------------------
+
+The ``presets=`` Hydra override selects the physics backend and renderer at runtime:
+
+.. code-block:: bash
+
+   # Newton (Kit-less)
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=newton \
+     --visualizer newton
+
+   # PhysX (Kit — requires Isaac Sim)
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=physx
+
+   # Newton with a specific visualizer
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=newton \
+     --visualizer viser
+
+Kit-less visualizer options: ``newton``, ``rerun``, ``viser``. Multiple can be
+combined: ``--visualizer newton,rerun``.
+
+.. seealso::
+
+   - :doc:`/source/features/hydra` — Hydra presets and configuration overrides
+   - :doc:`/source/features/visualization` — Visualizer backends and configuration
+   - :doc:`/source/how-to/configure_rendering` — Rendering mode presets and settings
+   - :ref:`isaaclab-installation-root` — Full installation guide with all methods
+
+Available Presets
+^^^^^^^^^^^^^^^^^
+
+Presets are combined with commas: ``presets=newton,newton_renderer,depth``.
+
+.. code-block:: bash
+
+   presets=newton,newton_renderer,rgb  # presets=physics,renderer,render mode
+   presets=newton,newton_renderer,depth
+   presets=physx,isaacsim_rtx_renderer,rgb
+   presets=physx,isaacsim_rtx_renderer,depth
+   presets=physx,isaacsim_rtx_renderer,albedo
+   presets=physx,isaacsim_rtx_renderer,simple_shading_constant_diffuse
+   presets=physx,isaacsim_rtx_renderer,simple_shading_diffuse_mdl
+   presets=physx,isaacsim_rtx_renderer,simple_shading_full_mdl
+   presets=newton,ovrtx_renderer,rgb
+   presets=newton,ovrtx_renderer,depth
+   presets=newton,ovrtx_renderer,albedo
+   presets=newton,ovrtx_renderer,simple_shading_constant_diffuse
+   presets=newton,ovrtx_renderer,simple_shading_diffuse_mdl
+   presets=newton,ovrtx_renderer,simple_shading_full_mdl
diff --git a/docs/source/setup/quickstart.rst b/docs/source/setup/quickstart.rst
