Consolidate simulation performance guidance

[AntoineRichard]

Description

Consolidates the standalone simulation performance how-to into the troubleshooting reference, where users are more likely to look for slow simulation and training guidance.

The previous page remains as a compatibility pointer so existing links continue to work. This also updates the Nsight profiling cross-reference, points broad tuning guidance to the maintained Isaac Sim performance guides, and synchronizes the setup-troubleshooting skill.

Type of change

• Documentation update

Release backport

• Backport this pull request to the active release branch after it merges into develop

Validation

• uv run --isolated --extra test -- make -C docs current-docs
• uv run --no-sync isaaclab -f
• uv run --no-project python tools/skills/cli.py check
• Baseline and skill-assisted slow-throughput routing evaluation

Checklist

• I have read the contribution guidelines.
• I have run the pre-commit checks.
• I have updated the relevant documentation and troubleshooting skill.
• The documentation builds with warnings treated as errors.
• A changelog fragment is not required because no source package changed.

[greptile-apps]

Greptile Summary

The PR consolidates simulation-performance guidance into the troubleshooting reference while retaining the former how-to page as a compatibility pointer.

• Removes the standalone performance guide from the how-to navigation and redirects readers to the new troubleshooting section.
• Updates the Nsight Systems cross-reference and links broader tuning topics to maintained upstream guides.
• Extends the setup-troubleshooting skill, routing reference, and evaluation coverage for slow simulation and training workloads.

Confidence Score: 5/5

The documentation-only PR appears safe to merge with its compatibility page and new cross-references intact.

The former source page remains available as an orphaned compatibility pointer, the new Sphinx labels and document targets resolve in source, and the troubleshooting skill links to guidance that satisfies its added routing and evaluation requirements.

Important Files Changed

Filename	Overview
docs/source/how-to/simulation_performance.rst	Replaces the standalone guide with an orphaned compatibility page that points to the consolidated troubleshooting guidance.
docs/source/refs/troubleshooting.rst	Adds profiling-first guidance for slow workloads, common PhysX performance checks, and maintained upstream references.
docs/source/how-to/profile_with_nsys.rst	Updates the broader-performance cross-reference to the new labeled troubleshooting section.
skills/user/setup-troubleshooting/SKILL.md	Expands the skill’s scope and workflow to route simulation-performance questions to the official troubleshooting documentation.
skills/user/setup-troubleshooting/evaluations.md	Adds an evaluation scenario covering profiling, GPU collider fallback, and upstream performance guidance.
skills/user/setup-troubleshooting/reference.md	Adds poor simulation or training throughput to the common-failure routing table.

_{Reviews (1): Last reviewed commit: "Consolidate simulation performance guida..." | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The consolidation is coherent, but the compatibility stub removes the retired page’s generated section anchors, so existing deep links to those sections are no longer preserved.

• Design and architecture: Moving slow-simulation guidance into the troubleshooting reference and deferring broad tuning to maintained upstream guides is coherent. Retaining the old page as a stub preserves page-level links, but not links to its former sections.
• API: No code, CLI, or configuration APIs change. The new simulation-performance-troubleshooting label and relative documentation references are consistent, but generated anchors such as #collision-geometries and #cpu-governor-settings-on-linux disappear from the compatibility page and should be preserved or redirected.
• Implementation: The troubleshooting content, Nsight cross-reference, skill workflow, routing table, and evaluation scenario are synchronized. The remaining fix is to add explicit compatibility targets for the removed headings on the stub or at their replacement destination.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🔵 Suggestion · Api — Legacy section anchors lost on stub page

The stub replaces all prior headings, so generated anchors such as #collision-geometries, #cpu-governor-settings-on-linux, and #additional-performance-guides no longer exist. Deep links that include those fragments land on the pointer page without resolving, which partially undercuts the stated link-compatibility goal. Consider adding explicit .. _...: targets on this page (or in the new troubleshooting section) for the retired heading anchors.

[kellyguo11]

run-ci

[isaaclab-bot]

Backported to release/3.0.0 as a22c3fa.