Deprecate IO descriptors

[AntoineRichard]

Description

Deprecate IO descriptors in Isaac Lab 3.0 ahead of their removal in Isaac Lab
3.2.

This change:

• marks the stable and Warp-specific descriptor APIs as deprecated;
• emits a FutureWarning from public descriptor collection/export entrypoints;
• marks the shared --export_io_descriptors training option as deprecated;
• preserves compatibility behavior through the 3.0 deprecation window;
• removes the IO descriptor tutorial and generated YAML examples; and
• directs supported RSL-RL/PyTorch deployments to the LEAPP export workflow.

Warp observation-dimension metadata remains temporarily because the Warp
frontend still consumes it for runtime buffer planning. LEAPP does not yet
replace that Warp-first path.

Type of change

• API deprecation (non-breaking compatibility change)
• Documentation update

Screenshots

Not applicable.

Verification

• ./isaaclab.sh -f
• ./isaaclab.sh -d
• Python compile checks for the affected packages
• Runtime warning smoke check
• Deleted tutorial/reference scan

No deprecation-specific tests were added; the public behavior remains available
during the deprecation window.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh -f
• 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 for every touched package
• My name already exists in CONTRIBUTORS.md

[greptile-apps]

Greptile Summary

Deprecates the stable and Warp-specific IO descriptor APIs ahead of removal in Isaac Lab 3.2 while preserving their compatibility behavior.

• Adds FutureWarning emission to public descriptor collection and export entrypoints.
• Keeps an internal warning-free collection path and retains Warp observation-dimension metadata used for buffer allocation.
• Marks the shared training flag and related configuration/API documentation as deprecated.
• Removes the IO descriptor tutorial and generated YAML examples, directing supported deployments toward LEAPP.

Confidence Score: 5/5

The PR appears safe to merge, with descriptor compatibility and Warp runtime metadata behavior preserved throughout the deprecation window.

Public descriptor use now emits a warning while internal collection retains the previous output behavior, and normal Warp initialization continues to read dimension metadata directly without entering deprecated export paths.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/envs/manager_based_env.py	Adds warning-emitting public descriptor entrypoints and a compatibility-preserving internal collector.
source/isaaclab/isaaclab/managers/observation_manager.py	Separates deprecated public descriptor access from the unchanged descriptor collection implementation.
source/isaaclab/isaaclab/managers/action_manager.py	Adds deprecation documentation and warning behavior while retaining action descriptor serialization.
source/isaaclab/isaaclab/envs/utils/io_descriptors.py	Documents descriptor models and decorators as deprecated and centralizes warning emission.
source/isaaclab_experimental/isaaclab_experimental/envs/manager_based_env_warp.py	Mirrors stable deprecation behavior without affecting Warp runtime dimension inference.
source/isaaclab_experimental/isaaclab_experimental/managers/observation_manager.py	Preserves Warp descriptor metadata collection and runtime buffer-dimension planning.
source/isaaclab_experimental/isaaclab_experimental/envs/utils/io_descriptors.py	Deprecates the Warp-specific decorator while retaining its runtime metadata contract.
source/isaaclab_rl/isaaclab_rl/entrypoints/common.py	Marks the shared descriptor-export training option as deprecated while preserving flag behavior.
docs/source/policy_deployment/index.rst	Removes the deprecated IO descriptor tutorial from the deployment documentation navigation.

_{Reviews (1): Last reviewed commit: "Deprecate IO descriptors" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The deprecation preserves IO descriptor behavior while adding FutureWarning emissions at public collection and export boundaries. Documentation, CLI help, and package changelog fragments consistently identify the Isaac Lab 3.2 removal target and LEAPP migration path.

• Design and architecture: The public warning/private collector split avoids duplicate warnings during nested environment-to-manager collection. Stable and Warp-first paths remain aligned, while Warp output-dimension metadata is explicitly retained for runtime buffer planning.
• API: Existing descriptor return structures, export behavior, and the --export_io_descriptors flag remain available during the deprecation window. A non-blocking compatibility tradeoff is that environment exports now call private manager collectors directly, so downstream subclasses overriding only the public descriptor property will no longer customize that path.
• Implementation: The stable and experimental environment collectors resolve to corresponding action and observation manager helpers, preserving the prior formatting and YAML generation logic. Warning stack levels point to external callers, and the removed tutorial, toctree entry, and referenced generated YAML examples were deleted together.

No blocking issues. No inline issue met the actionable-evidence threshold; the assessment above records the review feedback.

Automated review; human maintainers own approval decisions.

[StafaH]

Can't we just deprecate it altogether without warning, and just keep it in the migration guide?

[AntoineRichard]

It should only warn if the users collect the descriptors and the docstring lets the users know this is getting removed. It feels like the right balance to me.

[kellyguo11]

are we sure nobody is using these? I think Isaac Sim team might still be depending on the IO descriptors for their policy deployment work.

[AntoineRichard]

@kellyguo11 it's not removing them, just removing them from the doc, and pushing folks to use Leapp instead!