Cherry-picks doc fixes/updates, demo/benchmark scripts, default num_envs, shutdown error, mjcf fix

[kellyguo11]

Description

Cherry-pick PRs from develop:

• Fix Demo Scripts (h1_locomotion.py and quadcopter.py) #5866
• Updates environment and installation docs #5879
• Fixes drone navigation, camera benchmark, and kitless shutdown errors #5882
• Updates jax instructions for Spark #5884
• Fixes MJCF importer extension and updates stale importer docs #5889

[isaaclab-review-bot]

🤖 Automated Review for PR #5888

This cherry-pick PR collects fixes from PRs #5866, #5879, and #5884 into the release/3.0.0-beta2 branch, adding documentation infrastructure improvements, demo script bug fixes, and new maintainer tooling for auto-generating environment documentation.

---

📋 Summary

Category	Files	Assessment
Documentation Infrastructure	docs/_extensions/isaaclab_docs.py, docs/conf.py	✅ Well-structured
Environment Doc Tooling	tools/environ_docs.py, tools/update_environments_rst.py, tools/test/	✅ Good design with tests
Demo Bug Fixes	scripts/demos/h1_locomotion.py, scripts/demos/quadcopter.py	✅ Correct API migration
Doc Content Updates	20+ .rst files	✅ Consistent branch references
CI/Tests	test_uv_pip_install_isaaclab_rl_tasks_imports_rl_tasks.py	✅ Good coverage addition

---

🔍 Findings

1. Missing Cherry-Pick: PR #5882 Not Included (Medium)

File: PR description
Issue: The PR description references cherry-picking #5882 (drone navigation num_envs default fix, camera benchmark fix, and __del__ shutdown error fix), but this PR's commits only include #5866, #5884, and #5879. None of the 8 files from #5882 are present in the diff:

• source/isaaclab/isaaclab/envs/direct_rl_env.py
• source/isaaclab/isaaclab/envs/direct_marl_env.py
• source/isaaclab/isaaclab/envs/manager_based_env.py
• scripts/benchmarks/benchmark_cameras.py
• Drone navigation config files

The PR title also mentions "drone navigation default num_envs, shutdown error" which are exclusively from #5882. Consider either including the missing cherry-pick or updating the title/description to reflect actual content.

2. Broad Exception Suppression in _physics_names_for_docs (Low)

File: tools/environ_docs.py (line ~185)

with contextlib.suppress(Exception):
    names |= _infer_implicit_physics_names(task_name)

This suppresses all exceptions including TypeError, AttributeError, and other bugs. Since this is a documentation generation tool (not runtime), a narrower catch like (ImportError, KeyError, AttributeError, ValueError) would be safer to avoid silently masking real bugs during development. Alternatively, logging suppressed exceptions at debug level would aid maintainability.

3. CI: "Check for Broken Links" Failure is Transient (Info)

The CI failure is caused by a transient 502 response from https://github.com/isaac-sim/IsaacLab/pull/3174, which is unrelated to this PR's changes. This is a known flaky check.

---

✅ Verified Correctness

1. Quadcopter API fix (scripts/demos/quadcopter.py):
   robot.data.body_mass.torch[0].sum() is the correct public API, matching the pattern used in isaaclab/envs/mdp/events.py (self.asset.data.body_mass.torch.clone()). The [0] index correctly selects the first environment instance for this single-env demo.

2. H1 locomotion deprecation handler (scripts/demos/h1_locomotion.py):
   The import of handle_deprecated_rsl_rl_cfg and usage with metadata.version("rsl-rl-lib") exactly matches the pattern in scripts/reinforcement_learning/rsl_rl/train.py.

3. Sphinx extension (docs/_extensions/isaaclab_docs.py):
   Properly implements setup() with parallel_read_safe=True and parallel_write_safe=True. Directives correctly use SphinxDirective base class and nested_parse for RST generation.

4. docs/conf.py changes:
   Extension registration, sys.path insertion, exclude_patterns for include-only fragments, and rst_prolog with substitution are all correctly structured.

5. Environment doc tooling (tools/environ_docs.py):
   Well-designed with comprehensive test coverage in tools/test/test_environ_docs.py (276 lines of tests). The marker-based patch_environments_rst() approach is maintainable.

---

🏁 Verdict

No blocking issues. The one substantive observation is the missing #5882 cherry-pick which should either be included or removed from the description. The broad exception suppression in environ_docs.py is a minor maintainability concern. Otherwise, the code changes are correct and well-tested.

---

Update (commit 536cddc): New commit removes test_uv_pip_install_isaaclab_rl_tasks_imports_rl_tasks.py (CI test file). No new issues introduced. Previous findings (missing #5882 cherry-pick, broad exception suppression, inline suggestions on environ_docs.py and test_environ_docs.py) remain unaddressed but are non-blocking.

---

Update (commit 2d5015a): New commits add:

1. --viz kit flag to URDF/MJCF conversion examples in documentation (consistent across Linux/Windows tabs)
2. MJCF converter fix — enables isaacsim.asset.importer.mjcf extension before importing (addresses the "mjcf fix" from #5882)
3. Updated test_mjcf_converter.py to avoid enabling the extension in test setup, verifying the converter does it itself

✅ The MJCF fix is correct: uses get_extension_manager().set_extension_enabled_immediate() with a proper guard check. The test properly validates this behavior.

Previous findings status:

• Missing #5882 content: Partially addressed — MJCF fix is now included. The num_envs defaults and __del__ shutdown error fixes still appear absent.
• Broad exception suppression in environ_docs.py: Not addressed (non-blocking).
• Inline suggestions on environ_docs.py and test_environ_docs.py: Not addressed (non-blocking).

No new issues found in these changes.

[greptile-apps]

Greptile Summary

This cherry-pick bundles documentation fixes targeting release/3.0.0-beta2 (branch references, JAX install instructions, installation guide restructuring), plus two runtime fixes in demo scripts and a new auto-generation pipeline for the comprehensive environment list.

• Demo fixes: quadcopter.py replaces the deprecated root_view.get_masses() call with data.body_mass.torch[0].sum(), and h1_locomotion.py adds the missing handle_deprecated_rsl_rl_cfg call that was triggering a shutdown error.
• Auto-generated environment table: A new Sphinx extension (isaaclab_docs.py) and tooling (tools/environ_docs.py, tools/update_environments_rst.py) generate the comprehensive environment list directly from the Gym registry, removing the need to maintain it by hand; the new table also correctly reflects many additional environments and updated preset/RL-library labels.

Confidence Score: 4/5

Safe to merge. The two demo fixes are straightforward API-migration patches and the documentation restructuring is extensive but low-risk.

Changes are largely documentation and tooling. The two demo script fixes are small and targeted. The new environ_docs.py pipeline has good unit-test coverage and the generated environments.rst output matches expectations. The only notes are a test that implicitly depends on live task registration and a minor robustness gap in get_workflow; neither affects runtime behaviour.

tools/test/test_environ_docs.py (live-task integration assertion) and tools/environ_docs.py (get_workflow string-check) are the only spots worth a second look.

Important Files Changed

Filename	Overview
scripts/demos/quadcopter.py	Fixes mass lookup from deprecated root_view.get_masses() to data.body_mass.torch[0].sum(). The [0] index is correct for this single-robot demo.
scripts/demos/h1_locomotion.py	Adds handle_deprecated_rsl_rl_cfg call to suppress the deprecation-related shutdown error when loading the pre-trained RSL-RL runner config.
tools/environ_docs.py	New utility for auto-generating the environments.rst table from the Gym registry; logic is well-structured with appropriate exception suppression around optional inference.
tools/update_environments_rst.py	New maintainer script; correctly handles read/write/check modes and exits with appropriate codes.
tools/test/test_environ_docs.py	Good unit test coverage for environ_docs helpers; one test (test_physics_names_for_docs_infers_physx_from_default) implicitly depends on live task registration, making it an integration test in unit clothing.
docs/_extensions/isaaclab_docs.py	New Sphinx extension generating branch-pinned clone/install code blocks; cleanly registered and supports overriding the branch via ISAACLAB_LATEST_BRANCH env var.
docs/conf.py	Registers the new Sphinx extension, sets isaaclab_latest_branch config value and rst_prolog, and moves installation include fragments to exclude_patterns.
docs/source/overview/environments.rst	Large update: adds auto-generation markers for the comprehensive environment list, corrects ovphysx (direct only) notes, and adds the _comprehensive-environment-list ref label.
source/isaaclab/test/install_ci/uv_pip/test_uv_pip_install_isaaclab_rl_tasks_imports_rl_tasks.py	New CI test verifying [all] wheel installs RL libraries without pulling in isaacsim; properly gated with @pytest.mark.docker and skip guard when uv is absent.
tools/wheel_builder/res/python_packages.toml	Minor comment update clarifying that [all] is for kit-less use and Newton must not be added here due to Isaac Sim pin conflicts.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Gym Registry\n gymnasium.register] -->|all registered specs| B[collect_environment_doc_rows\nenviron_docs.py]
    B --> C{is_training_task?}
    C -- No --> D[skip]
    C -- Yes --> E[enumerate_task_presets\npreset_cli]
    E --> F[_physics_names_for_docs\n+ implicit PhysX inference]
    B --> G[parse_rl_libraries_from_kwargs\n+ apply_rl_library_overrides]
    F --> H[format_presets_rst]
    G --> I[format_rl_libraries]
    H --> J[EnvironmentDocRow]
    I --> J
    J --> K[render_comprehensive_list_table]
    K --> L[patch_environments_rst\nenvironments.rst]
    L --> M{--check mode?}
    M -- Yes --> N[Exit 1 if stale\nExit 0 if up-to-date]
    M -- No --> O[Write updated environments.rst]

Loading

_{Reviews (1): Last reviewed commit: "update develop branch to release/3.0.0-b..." | Re-trigger Greptile}

[greptile-apps]

This test calls _physics_names_for_docs with a real task name, which internally calls _infer_implicit_physics_names("Isaac-Velocity-Flat-G1-v0"). That function loads the live env config from the registry, imports isaaclab_physx and isaaclab_tasks, and inspects actual preset objects. If the G1 task's default physics changes or the task is unregistered, the assertion silently fails because _physics_names_for_docs suppresses all exceptions and just returns ["newton_mjwarp"] — making the failure look like a logic regression rather than a missing dependency. The other tests in this file all use mock EnvSpec objects; this one should too.

Suggested change

	def test_physics_names_for_docs_infers_physx_from_default():
	names = _physics_names_for_docs(
	"Isaac-Velocity-Flat-G1-v0",
	{PresetTarget.PHYSICS: ["newton_mjwarp"], PresetTarget.DOMAIN: [], PresetTarget.RENDERER: []},
	)
	assert names == ["newton_mjwarp", "physx"]
	def test_physics_names_for_docs_infers_physx_from_default():
	# Integration assertion: depends on Isaac-Velocity-Flat-G1-v0 declaring PhysxCfg()
	# as its default physics preset (see _infer_implicit_physics_names).
	names = _physics_names_for_docs(
	"Isaac-Velocity-Flat-G1-v0",
	{PresetTarget.PHYSICS: ["newton_mjwarp"], PresetTarget.DOMAIN: [], PresetTarget.RENDERER: []},
	)
	# If this fails unexpectedly, verify the G1 task config still uses PhysxCfg() as default.
	assert names == ["newton_mjwarp", "physx"]

[greptile-apps]

get_workflow performs "ManagerBasedRLEnv" in entry_point without guarding for non-string entry points. If a task is registered with a callable, this raises TypeError. Adding an isinstance guard prevents silent mislabelling or a runtime error if that registration pattern is ever used.

Suggested change

	def get_workflow(entry_point: str) -> str:
	"""Return the human-readable workflow label for a Gym entry point."""
	if "ManagerBasedRLEnv" in entry_point:
	return "Manager Based"
	return "Direct"
	def get_workflow(entry_point: str) -> str:
	"""Return the human-readable workflow label for a Gym entry point."""
	if isinstance(entry_point, str) and "ManagerBasedRLEnv" in entry_point:
	return "Manager Based"
	return "Direct"

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!