diff --git a/docs/_extensions/isaaclab_docs.py b/docs/_extensions/isaaclab_docs.py new file mode 100644 index 000000000000..32606a7fbd99 --- /dev/null +++ b/docs/_extensions/isaaclab_docs.py @@ -0,0 +1,67 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Sphinx helpers for Isaac Lab documentation.""" + +from __future__ import annotations + +from docutils import nodes +from docutils.statemachine import StringList +from sphinx.util.docutils import SphinxDirective + + +def _branch(config) -> str: + """Return the branch or tag pinned in installation docs.""" + current_version = getattr(config, "smv_current_version", "") + if current_version: + return current_version + return getattr(config, "isaaclab_latest_branch", "main") + + +def _parse_rst(directive: SphinxDirective, content: str) -> list[nodes.Node]: + """Parse nested reST and return the generated document nodes.""" + source = directive.env.doc2path(directive.env.docname, base=False) + lines = StringList(content.splitlines(), source=source) + container = nodes.container() + directive.state.nested_parse(lines, 0, container) + return container.children + + +class IsaacLabCloneCommands(SphinxDirective): + """Render SSH/HTTPS clone tabs using copy-friendly ``code-block`` directives.""" + + has_content = False + + def run(self) -> list[nodes.Node]: + branch = _branch(self.config) + content = f"""\ +.. tab-set:: + + .. tab-item:: SSH + + .. code-block:: bash + + git clone git@github.com:isaac-sim/IsaacLab.git --branch {branch} + cd IsaacLab + + .. tab-item:: HTTPS + + .. code-block:: bash + + git clone https://github.com/isaac-sim/IsaacLab.git --branch {branch} + cd IsaacLab +""" + return _parse_rst(self, content) + + +def setup(app): + """Register Isaac Lab documentation directives.""" + app.add_config_value("isaaclab_latest_branch", "main", "env") + app.add_directive("isaaclab-clone-commands", IsaacLabCloneCommands) + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/conf.py b/docs/conf.py index d02e23b92e14..38686f640d8c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,7 @@ import os import sys +sys.path.insert(0, os.path.abspath("_extensions")) sys.path.insert(0, os.path.abspath("../source/isaaclab")) sys.path.insert(0, os.path.abspath("../source/isaaclab/isaaclab")) sys.path.insert(0, os.path.abspath("../source/isaaclab_assets")) @@ -42,6 +43,13 @@ full_version = f.read().strip() version = ".".join(full_version.split(".")[:3]) +# Latest branch referenced by installation documentation. +isaaclab_latest_branch = os.getenv("ISAACLAB_LATEST_BRANCH", "main") + +rst_prolog = f""" +.. |isaaclab_latest_branch| replace:: {isaaclab_latest_branch} +""" + # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -65,6 +73,7 @@ "sphinx_design", "sphinx_tabs.tabs", # backwards compatibility for building docs on v1.0.0 "sphinx_multiversion", + "isaaclab_docs", ] # mathjax hacks diff --git a/docs/source/deployment/index.rst b/docs/source/deployment/index.rst index 235a23c9d754..d30708a3ec12 100644 --- a/docs/source/deployment/index.rst +++ b/docs/source/deployment/index.rst @@ -18,19 +18,7 @@ Cloning the Repository Before building the container, clone the Isaac Lab repository (if not already done): -.. tab-set:: - - .. tab-item:: SSH - - .. code:: bash - - git clone git@github.com:isaac-sim/IsaacLab.git - - .. tab-item:: HTTPS - - .. code:: bash - - git clone https://github.com/isaac-sim/IsaacLab.git +.. isaaclab-clone-commands:: Next Steps ---------- diff --git a/docs/source/policy_deployment/02_gear_assembly/gear_assembly_policy.rst b/docs/source/policy_deployment/02_gear_assembly/gear_assembly_policy.rst index f324dae843c0..c26f0130929e 100644 --- a/docs/source/policy_deployment/02_gear_assembly/gear_assembly_policy.rst +++ b/docs/source/policy_deployment/02_gear_assembly/gear_assembly_policy.rst @@ -33,7 +33,7 @@ This environment has been successfully deployed on real UR10e robots without an **Scope of This Tutorial:** -This tutorial focuses exclusively on the **training part** of the sim-to-real transfer workflow in Isaac Lab. For the complete deployment workflow on the real robot, including the exact steps to set up the vision pipeline, robot interface and the ROS inference node to run your trained policy on real hardware, please refer to the `Isaac ROS Documentation `_. +This tutorial focuses exclusively on the **training part** of the sim-to-real transfer workflow in Isaac Lab. For the complete deployment workflow on the real robot, including the exact steps to set up the vision pipeline, robot interface and the ROS inference node to run your trained policy on real hardware, please refer to the `Isaac ROS Documentation `_. Overview -------- @@ -493,7 +493,7 @@ Replace ```` with the path to your training logs (e.g., ``logs/rsl_rl/g Step 3: Deploy on Real Robot ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once training is complete, follow the `Isaac ROS inference documentation `_ to deploy your policy. +Once training is complete, follow the `Isaac ROS inference documentation `_ to deploy your policy. The Isaac ROS deployment pipeline directly uses the trained model checkpoint (``.pt`` file) along with the ``agent.yaml`` and ``env.yaml`` configuration files generated during training. No additional export step is required. diff --git a/docs/source/setup/ecosystem.rst b/docs/source/setup/ecosystem.rst index 5978443ac21c..79792b7ed75d 100644 --- a/docs/source/setup/ecosystem.rst +++ b/docs/source/setup/ecosystem.rst @@ -147,7 +147,7 @@ to Isaac Lab, please reach out to us. .. _AirSim: https://microsoft.github.io/AirSim/ .. _DoorGym: https://github.com/PSVL/DoorGym/ .. _ManiSkill: https://github.com/haosulab/ManiSkill -.. _ThreeDWorld: https://www.threedworld.org/ +.. _ThreeDWorld: https://github.com/threedworld-mit/tdw .. _RoboSuite: https://robosuite.ai/ .. _MuJoCo: https://mujoco.org/ .. _MuJoCo Playground: https://playground.mujoco.org/ diff --git a/docs/source/setup/installation/include/src_clone_isaaclab.rst b/docs/source/setup/installation/include/src_clone_isaaclab.rst index 844cac2f3fd1..3833ad817016 100644 --- a/docs/source/setup/installation/include/src_clone_isaaclab.rst +++ b/docs/source/setup/installation/include/src_clone_isaaclab.rst @@ -10,20 +10,7 @@ Cloning Isaac Lab Clone the Isaac Lab repository into your project's workspace: -.. tab-set:: - - .. tab-item:: SSH - - .. code:: bash - - git clone git@github.com:isaac-sim/IsaacLab.git - - .. tab-item:: HTTPS - - .. code:: bash - - git clone https://github.com/isaac-sim/IsaacLab.git - +.. isaaclab-clone-commands:: We provide a helper executable `isaaclab.sh `_ and `isaaclab.bat `_ for Linux and Windows diff --git a/docs/source/setup/quickstart.rst b/docs/source/setup/quickstart.rst index 70b5c7a7c6ea..97b058b8f3a4 100644 --- a/docs/source/setup/quickstart.rst +++ b/docs/source/setup/quickstart.rst @@ -100,19 +100,7 @@ and now we can install the Isaac Sim packages. Finally, we can install Isaac Lab. To start, clone the repository using the following -.. tab-set:: - - .. tab-item:: SSH - - .. code:: bash - - git clone git@github.com:isaac-sim/IsaacLab.git - - .. tab-item:: HTTPS - - .. code:: bash - - git clone https://github.com/isaac-sim/IsaacLab.git +.. isaaclab-clone-commands:: Installation is now as easy as navigating to the repo and then calling the root script with the ``--install`` flag!