Skip to content

[Docs] Overhaul Tutorial - #7435

Merged
kellyguo11 merged 6 commits into
isaac-sim:developfrom
StafaH:docs/overhaul-so101-tutorial
Sep 4, 2026
Merged

[Docs] Overhaul Tutorial#7435
kellyguo11 merged 6 commits into
isaac-sim:developfrom
StafaH:docs/overhaul-so101-tutorial

Conversation

@StafaH

@StafaH StafaH commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Description

Add one end-to-end SO-101 vial-placement tutorial based on the maintained IsaacLabTutorial project while preserving the focused Isaac Lab mini tutorials.

The new page:

  • appears as a standalone Tutorial directly below Quickstart
  • points to the IsaacLabTutorial main branch and its maintained rollout
  • explains setup, package discovery, scene and MDP design, reset curriculum, validation, state-policy training, camera-policy distillation, evaluation, and extension
  • connects the downstream project structure to the Isaac Lab template generator

The existing mini tutorials remain under the expandable Tutorials entry. The direct-workflow LEAPP tutorial and its annotation prerequisites are also retained. The deprecated Jetbot walkthrough remains removed.

No source packages are changed, so no package changelog fragment is required.

Type of change

  • Documentation update

Screenshots

The tutorial includes the SO-101 vial-placement rollout and a six-card navigation menu. The homepage navigation places Tutorial below Quickstart and keeps the mini tutorials under Tutorials.

Validation

  • uv run isaaclab -f
  • uv run --isolated --extra dev -- make -C docs current-docs
  • Verified rendered navigation and the external IsaacLabTutorial/main rollout URL

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
  • Tests are not required for this documentation-only change
  • No changelog fragment is required because no source package changed
  • My name already exists in CONTRIBUTORS.md

Release backport

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

@StafaH
StafaH requested a review from a team August 29, 2026 17:28
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Aug 29, 2026
@greptile-apps

greptile-apps Bot commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR replaces the deprecated tutorial collection and Jetbot walkthrough with one end-to-end SO-101 vial-placement guide based on the maintained IsaacLabTutorial project.

  • Adds setup, package discovery, task design, validation, training, evaluation, and extension guidance.
  • Removes obsolete tutorial pages and images while updating references in maintained documentation.
  • Adds an embedded reference rollout, although its current static URL is not emitted by the documentation build.

Confidence Score: 4/5

The broken rollout asset must be fixed before merging so the central tutorial media works on the published site.

The tutorial references an MP4 under a static subdirectory that is neither configured for Sphinx copying nor handled by another build step, so the generated page cannot load the advertised rollout.

Files Needing Attention: docs/source/tutorials/index.rst

Important Files Changed

Filename Overview
docs/source/tutorials/index.rst Replaces the tutorial index with the SO-101 workflow, but embeds its rollout at a static URL that the Sphinx build does not produce.
docs/index.rst Removes the deprecated walkthrough from navigation while retaining the rewritten tutorials index.
docs/source/how-to/add_own_library.rst Replaces references to removed tutorials with maintained reinforcement-learning documentation.
docs/source/overview/core-concepts/task_workflows.rst Redirects manager-based workflow guidance to the new SO-101 tutorial.
docs/source/policy_deployment/05_leapp/exporting_policies_with_leapp.rst Replaces the deleted LEAPP tutorial with concise current export and deployment guidance.

Reviews (1): Last reviewed commit: "Replace tutorials with SO-101 vial place..." | Re-trigger Greptile

Comment thread docs/source/tutorials/index.rst Outdated

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isaac Lab Review Bot

The tutorial consolidation is coherent, but three documentation integration gaps need correction: the direct-workflow LEAPP export prerequisite was removed, the event-randomization skill was not synchronized when its declared source pages were deleted, and the raw HTML video uses an incorrect output-relative path.

  • Design and architecture: Replacing the disconnected tutorial collection with one downstream-project walkthrough is a reasonable restructuring. However, deleting both pages declared as the source of truth for the event-randomization skill without updating that repository-owned skill leaves its maintained guidance disconnected from the documentation architecture.
  • API: The surviving cross-reference labels are appropriately retargeted, but the replacement LEAPP text says direct-workflow policies can be exported without explaining that their environments must first provide LEAPP input, output, and state annotations. That prerequisite must remain documented or link to a maintained guide.
  • Implementation: The embedded rollout is emitted through raw HTML, so Sphinx will not rewrite its URL. From source/tutorials/index.html, ../_static/... resolves under source/_static rather than the build-root _static; the path should use ../../_static/.... The repository-owned event-randomization skill also needs to be repointed or updated alongside deletion of its source-of-truth pages.

Minor fixes needed. Posted 3 actionable findings inline.

Automated review; human maintainers own approval decisions.

Comment thread docs/source/policy_deployment/05_leapp/exporting_policies_with_leapp.rst Outdated
Comment thread docs/source/tutorials/index.rst Outdated
Comment thread docs/source/tutorials/index.rst Outdated
@StafaH

StafaH commented Aug 29, 2026

Copy link
Copy Markdown
Contributor Author

run-ci

@isaaclab-bot isaaclab-bot Bot added ci:run-docker Trigger the on-demand Docker and GPU CI workflow and removed ci:run-docker Trigger the on-demand Docker and GPU CI workflow labels Aug 29, 2026
@ooctipus
ooctipus enabled auto-merge (squash) August 29, 2026 23:58
ooctipus and others added 2 commits August 29, 2026 20:34
Four modify/delete conflicts, all from isaac-sim#7407 adding --extra flags to command
lines in tutorial pages this branch removes. Kept the deletions: the surviving
--extra fixes merged cleanly, and the new tutorial only invokes rsl_rl, which
needs no extra.
Comment thread docs/source/_static/tutorials/so101_vial_placement.gif Outdated
Comment thread docs/source/tutorials/index.rst Outdated
Comment thread docs/source/policy_deployment/05_leapp/exporting_policies_with_leapp.rst Outdated

@AntoineRichard AntoineRichard left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the SO101 example covers all of the things that we removed? I'm all for something more integrated, but it's also nice to have simple blocks to explain specific API bits. Otherwise LGTM with Kelly's comments.

…101-tutorial

# Conflicts:
#	docs/index.rst
#	docs/source/how-to/multi_asset_spawning.rst
#	docs/source/policy_deployment/05_leapp/exporting_direct_workflow_policies_with_leapp.rst
#	docs/source/policy_deployment/05_leapp/exporting_policies_with_leapp.rst
#	docs/source/tutorials/04_sensors/add_sensors_on_robot.rst
#	docs/source/tutorials/index.rst
@kellyguo11

Copy link
Copy Markdown
Contributor

run-ci

@isaaclab-bot isaaclab-bot Bot added ci:run-docker Trigger the on-demand Docker and GPU CI workflow and removed ci:run-docker Trigger the on-demand Docker and GPU CI workflow labels Sep 4, 2026
@kellyguo11
kellyguo11 disabled auto-merge September 4, 2026 22:57
@kellyguo11
kellyguo11 merged commit 493ee92 into isaac-sim:develop Sep 4, 2026
53 checks passed
kellyguo11 pushed a commit that referenced this pull request Sep 5, 2026
Backports #7435 to `release/3.0.0`.

The release branch advanced after this backport was created, causing a
conflict in `docs/index.rst`. The original PR removes the walkthrough
entry, while the updated release branch removes the old own-project
entry. The resolution preserves both removals.

Deterministic validation confirmed that the final diff against the
updated release base has the same stable patch ID as the original merged
change and changes no paths outside the original PR.

| Field | Commit |
|---|---|
| Original merged change | `493ee92f8a9ccf62d1cd199ce90075fcd78c722a` |
| Updated release base | `e79616ee6b8cc344bfdc2ea812a6dec25769748d` |
| Resolved backport | `26e188e23eeaae24a1608407f62cdb43e1a1c8cc` |

Validation:
- `uv run isaaclab -f`
- `uv run --isolated --extra test -- make -C docs current-docs`

Co-authored-by: Mustafa H <34825877+StafaH@users.noreply.github.com>
Co-authored-by: Mustafa Haiderbhai <mhaiderbhai@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants