isaaclab-updating-environment-docs

# Updating Environment Documentation ## When To Use Use this skill whenever a registered environment is added or renamed, or when its accepted ``physics=``, ``renderer=``, or ``presets=`` selectors change. ## Workflow 1. Read the task registration and configuration to identify its training ID, inference ID, workflow, RL-library entry points, and selectable presets. Use versionless ``Isaac-`` IDs for core tasks and versionless ``IsaacContrib-`` IDs for contributed tasks. Preserve released IDs as deprecated aliases when renaming is necessary. Distinguish selectable presets from fixed configuration: if a task supports only one hard-wired backend, leave its Presets cell empty instead of adding or documenting a single-option selector. 2. Add a representative screenshot under ``docs/source/_static/environment-previews/`` when the world is new. Assign the image to the task's generated row in ``docs/source/_static/css/environment-browser.js`` before running the updater. Capture screenshots with the Kit visualizer so their rendering matches the existing previews unless the task deliberately documents another visualizer. 3. Run the registry-backed updater: ```bash uv run python tools/update_environments_rst.py ``` This rewrites the environment-browser task rows from the Gym registry and groups names under ``physics=``, ``renderer=``, and ``presets=``. Existing preview-image assignments are preserved. 4. Review the generated diff. Do not edit selector data between the environment-browser marker comments by hand. 5. Confirm the environment browser contains the task and agrees with the task's accepted selectors. 6. Follow the [contribution guide's documentation validation guidance](../../../docs/source/refs/contributing.rst#contributing-documentation): use incremental HTML previews while editing and require one clean, warning-free build of the final documentation update before publishing the PR. ## Validation Run: ```bash uv run python tools/update_environments_rst.py --check uv run python scripts/environments/list_envs.py --show_presets uv run --no-project python tools/skills/cli.py check ``` Run the guide's HTML preview or final clean build as appropriate, using the ``dev`` extra for Sphinx dependencies. Require the checks and final documentation build to exit successfully with no warnings or errors. Inspect the compiled environment browser in the documentation build output and verify that every new image and task selector renders correctly. ## Maintenance Keep this workflow synchronized with the environment-browser markers, the registry collector, the preset CLI, and the environment-list script. When those tools change, update the source documentation behavior first and keep this skill as a concise routing checklist. ## References - [Environment browser](../../../docs/source/setup/environments.rst) - [Environment documentation collector](../../../tools/environ_docs.py) - [Environment documentation updater](../../../tools/update_environments_rst.py) - [Environment list script](../../../scripts/environments/list_envs.py) - [Preset CLI](../../../source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py)