From d56c3b91fcbf6eb1064cc473f003b4236b71a6c6 Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 13:32:06 +0200 Subject: [PATCH 1/8] fixes more build issues --- docs/conf.py | 3 ++- docs/source/overview/environments.rst | 3 --- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3bdf99666ed..28580574b26 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -122,7 +122,7 @@ "python": ("https://docs.python.org/3", None), "numpy": ("https://numpy.org/doc/stable/", None), "trimesh": ("https://trimesh.org/", None), - "torch": ("https://pytorch.org/docs/stable/", None), + "torch": ("https://docs.pytorch.org/docs/stable", None), "isaacsim": ("https://docs.isaacsim.omniverse.nvidia.com/5.0.0/py/", None), "gymnasium": ("https://gymnasium.farama.org/", None), "warp": ("https://nvidia.github.io/warp/", None), @@ -162,6 +162,7 @@ "isaacsim.core.api", "isaacsim.core.cloner", "isaacsim.core.version", + "isaacsim.core.utils", "isaacsim.robot_motion.motion_generation", "isaacsim.gui.components", "isaacsim.asset.importer.urdf", diff --git a/docs/source/overview/environments.rst b/docs/source/overview/environments.rst index c4925adfb94..89d3e70440d 100644 --- a/docs/source/overview/environments.rst +++ b/docs/source/overview/environments.rst @@ -157,7 +157,6 @@ for the lift-cube environment: .. |gr1_pick_place| image:: ../_static/tasks/manipulation/gr-1_pick_place.jpg .. |surface-gripper| image:: ../_static/tasks/manipulation/ur10_stack_surface_gripper.jpg .. |gr1_pp_waist| image:: ../_static/tasks/manipulation/gr-1_pick_place_waist.jpg -.. |surface-gripper| image:: ../_static/tasks/manipulation/ur10_stack_surface_gripper.jpg .. |galbot_stack| image:: ../_static/tasks/manipulation/galbot_stack_cube.jpg .. |reach-franka-link| replace:: `Isaac-Reach-Franka-v0 `__ @@ -177,8 +176,6 @@ for the lift-cube environment: .. |short-suction-link| replace:: `Isaac-Stack-Cube-UR10-Short-Suction-IK-Rel-v0 `__ .. |gr1_pp_waist-link| replace:: `Isaac-PickPlace-GR1T2-WaistEnabled-Abs-v0 `__ .. |galbot_stack-link| replace:: `Isaac-Stack-Cube-Galbot-Left-Arm-Gripper-RmpFlow-v0 `__ -.. |long-suction-link| replace:: `Isaac-Stack-Cube-UR10-Long-Suction-IK-Rel-v0 `__ -.. |short-suction-link| replace:: `Isaac-Stack-Cube-UR10-Short-Suction-IK-Rel-v0 `__ .. |cube-shadow-link| replace:: `Isaac-Repose-Cube-Shadow-Direct-v0 `__ .. |cube-shadow-ff-link| replace:: `Isaac-Repose-Cube-Shadow-OpenAI-FF-Direct-v0 `__ From aeea789804c8165058d42a074ac36935db55728c Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 13:49:10 +0200 Subject: [PATCH 2/8] adds code skeleton to snippets --- docs/source/refs/contributing.rst | 56 ++++++++ docs/source/refs/snippets/code_skeleton.py | 155 +++++++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 docs/source/refs/snippets/code_skeleton.py diff --git a/docs/source/refs/contributing.rst b/docs/source/refs/contributing.rst index f4bc45003b7..01f4da6613a 100644 --- a/docs/source/refs/contributing.rst +++ b/docs/source/refs/contributing.rst @@ -237,6 +237,62 @@ For documentation, we adopt the `Google Style Guide `__ for generating the documentation. Please make sure that your code is well-documented and follows the guidelines. +Code Structure +^^^^^^^^^^^^^^ + +We follow a specific structure for the codebase. This helps in maintaining the codebase and makes it easier to +understand. + +In a Python file, we follow the following structure: + +.. code:: python + + # Imports: These are sorted by the pre-commit hooks. + # Constants + # Functions (public) + # Classes (public) + # Functions (private) + # Classes (private) + +Imports are sorted by the pre-commit hooks. Unless there is a good reason to do otherwise, please do not +import the modules inside functions or classes. To deal with circular imports, we use the +:obj:`typing.TYPE_CHECKING` variable. Please refer to the `Circular Imports`_ section for more details. + +Python does not have a concept of private and public classes and functions. However, we follow the +convention of prefixing the private functions and classes with an underscore. +The public functions and classes are the ones that are intended to be used by the users. The private +functions and classes are the ones that are intended to be used internally in that file. +Irrespective of the public or private nature of the functions and classes, we follow the Style Guide +for the code and make sure that the code and documentation are consistent. + +Similarly, within Python classes, we follow the following structure: + +.. code:: python + + # Constants + # Class variables (public or private): Must have the type hint ClassVar[type] + # Dunder methods: __init__, __del__ + # Representation: __repr__, __str__ + # Properties: @property + # Instance methods (public) + # Class methods (public) + # Static methods (public) + # Instance methods (private) + # Class methods (private) + # Static methods (private) + +The rule of thumb is that the functions within the classes are ordered in the way a user would +expect to use them. For instance, if the class contains the method :meth:`initialize`, :meth:`reset`, +:meth:`update`, and :meth:`close`, then they should be listed in the order of their usage. +The same applies for private functions in the class. Their order is based on the order of call inside the +class. + +.. dropdown:: Code skeleton + :icon: code + + .. literalinclude:: snippets/code_skeleton.py + :language: python + Circular Imports ^^^^^^^^^^^^^^^^ diff --git a/docs/source/refs/snippets/code_skeleton.py b/docs/source/refs/snippets/code_skeleton.py new file mode 100644 index 00000000000..cf0385279b6 --- /dev/null +++ b/docs/source/refs/snippets/code_skeleton.py @@ -0,0 +1,155 @@ +# Copyright (c) 2022-2025, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +import os +import sys +from typing import ClassVar + + +DEFAULT_TIMEOUT: int = 30 +"""Default timeout for the task.""" + +_MAX_RETRIES: int = 3 # private constant (note the underscore) +"""Maximum number of retries for the task.""" + + +def run_task(task_name: str): + """Run a task by name. + + Args: + task_name: The name of the task to run. + """ + print(f"Running task: {task_name}") + + +class TaskRunner: + """Runs and manages tasks.""" + + DEFAULT_NAME: ClassVar[str] = "runner" + """Default name for the runner.""" + + _registry: ClassVar[dict] = {} + """Registry of runners.""" + + def __init__(self, name: str): + """Initialize the runner. + + Args: + name: The name of the runner. + """ + self.name = name + self._tasks = [] # private instance variable + + def __del__(self): + """Clean up the runner.""" + print(f"Cleaning up {self.name}") + + def __repr__(self) -> str: + return f"TaskRunner(name={self.name!r})" + + def __str__(self) -> str: + return f"TaskRunner: {self.name}" + + """ + Properties. + """ + + @property + def task_count(self) -> int: + return len(self._tasks) + + """ + Operations. + """ + + def initialize(self): + """Initialize the runner.""" + print("Initializing runner...") + + def update(self, task: str): + """Update the runner with a new task. + + Args: + task: The task to add. + """ + self._tasks.append(task) + print(f"Added task: {task}") + + def close(self): + """Close the runner.""" + print("Closing runner...") + + """ + Operations: Registration. + """ + + @classmethod + def register(cls, name: str, runner: "TaskRunner"): + """Register a runner. + + Args: + name: The name of the runner. + runner: The runner to register. + """ + if name in cls._registry: + _log_error(f"Runner {name} already registered. Skipping registration.") + return + cls._registry[name] = runner + + @staticmethod + def validate_task(task: str) -> bool: + """Validate a task. + + Args: + task: The task to validate. + + Returns: + True if the task is valid, False otherwise. + """ + return bool(task and task.strip()) + + """ + Internal operations. + """ + + def _reset(self): + """Reset the runner.""" + self._tasks.clear() + + @classmethod + def _get_registry(cls) -> dict: + """Get the registry.""" + return cls._registry + + @staticmethod + def _internal_helper(): + """Internal helper.""" + print("Internal helper called.") + + +""" +Helper operations. +""" + + +def _log_error(message: str): + """Internal helper to log errors. + + Args: + message: The message to log. + """ + print(f"[ERROR] {message}") + + +class _TaskHelper: + """Private utility class for internal task logic.""" + + def compute(self) -> int: + """Compute the result. + + Returns: + The result of the computation. + """ + return 42 From 3e3063e5893761d0186b29d08647a89413f3c12e Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 13:58:47 +0200 Subject: [PATCH 3/8] clarifies pr template size --- .github/PULL_REQUEST_TEMPLATE.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e9176cc47f5..5ebe77b7f43 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,6 +4,8 @@ Thank you for your interest in sending a pull request. Please make sure to check the contribution guidelines. Link: https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html + +💡 Please try to keep PRs small and focused. Large PRs are harder to review and merge. --> Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. @@ -21,8 +23,8 @@ is demanded by more than one party. --> - Bug fix (non-breaking change which fixes an issue) - New feature (non-breaking change which adds functionality) -- Breaking change (fix or feature that would cause existing functionality to not work as expected) -- This change requires a documentation update +- Breaking change (existing functionality will not work without user modification) +- Documentation update ## Screenshots From 0cb75abfadcbba391ee68ad30b068fef2a8b302a Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 13:59:05 +0200 Subject: [PATCH 4/8] makes tools and testing as main sections --- docs/source/refs/contributing.rst | 53 ++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/docs/source/refs/contributing.rst b/docs/source/refs/contributing.rst index 01f4da6613a..03a20f47571 100644 --- a/docs/source/refs/contributing.rst +++ b/docs/source/refs/contributing.rst @@ -470,15 +470,47 @@ We summarize the key points below: Unit Testing -^^^^^^^^^^^^ +------------ We use `pytest `__ for unit testing. Good tests not only cover the basic functionality of the code but also the edge cases. They should be able to catch regressions and ensure that the code is working as expected. Please make sure that you add tests for your changes. +.. tab-set:: + :sync-group: os + + .. tab-item:: :icon:`fa-brands fa-linux` Linux + :sync: linux + + .. code-block:: bash + + # Run all tests + ./isaaclab.sh --test # or "./isaaclab.sh -t" + + # Run all tests in a particular file + ./isaaclab.sh -p -m pytest source/isaaclab/test/deps/test_torch.py + + # Run a particular test + ./isaaclab.sh -p -m pytest source/isaaclab/test/deps/test_torch.py::test_array_slicing + + .. tab-item:: :icon:`fa-brands fa-windows` Windows + :sync: windows + + .. code-block:: bash + + # Run all tests + isaaclab.bat --test # or "isaaclab.bat -t" + + # Run all tests in a particular file + isaaclab.bat -p -m pytest source/isaaclab/test/deps/test_torch.py + + # Run a particular test + isaaclab.bat -p -m pytest source/isaaclab/test/deps/test_torch.py::test_array_slicing + + Tools -^^^^^ +----- We use the following tools for maintaining code quality: @@ -491,6 +523,19 @@ Please check `here `__ for instructions to set these up. To run over the entire repository, please execute the following command in the terminal: -.. code:: bash +.. tab-set:: + :sync-group: os + + .. tab-item:: :icon:`fa-brands fa-linux` Linux + :sync: linux + + .. code-block:: bash + + ./isaaclab.sh --format # or "./isaaclab.sh -f" + + .. tab-item:: :icon:`fa-brands fa-windows` Windows + :sync: windows + + .. code-block:: bash - ./isaaclab.sh --format # or "./isaaclab.sh -f" + isaaclab.bat --format # or "isaaclab.bat -f" From 3076a95826c2d778672b1311e2b9275e5faa2c88 Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 14:13:56 +0200 Subject: [PATCH 5/8] adds ref to style --- docs/source/refs/contributing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/refs/contributing.rst b/docs/source/refs/contributing.rst index 03a20f47571..825b8451a1a 100644 --- a/docs/source/refs/contributing.rst +++ b/docs/source/refs/contributing.rst @@ -54,6 +54,9 @@ Please ensure that your code is well-formatted, documented and passes all the te Large pull requests are difficult to review and may take a long time to merge. +More details on the code style and testing can be found in the `Coding Style`_ and `Unit Testing`_ sections. + + Contributing Documentation -------------------------- From 4425e276f2a4e60c5d776b9ea511303fafd952fe Mon Sep 17 00:00:00 2001 From: Mayank Mittal Date: Tue, 9 Sep 2025 15:09:27 +0200 Subject: [PATCH 6/8] adds check for contribution guidelines --- .github/PULL_REQUEST_TEMPLATE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5ebe77b7f43..ee9fa4ebdc5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -42,6 +42,7 @@ To upload images to a PR -- simply drag and drop an image while in edit mode and ## Checklist +- [ ] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings From d4ad39b96c4d92115dc67e22f2ed180a5460cd43 Mon Sep 17 00:00:00 2001 From: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com> Date: Tue, 9 Sep 2025 17:30:38 +0200 Subject: [PATCH 7/8] Update docs/source/refs/contributing.rst Co-authored-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com> Signed-off-by: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com> --- docs/source/refs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/refs/contributing.rst b/docs/source/refs/contributing.rst index 825b8451a1a..1bfd600e401 100644 --- a/docs/source/refs/contributing.rst +++ b/docs/source/refs/contributing.rst @@ -254,8 +254,8 @@ In a Python file, we follow the following structure: # Constants # Functions (public) # Classes (public) - # Functions (private) - # Classes (private) + # _Functions (private) + # _Classes (private) Imports are sorted by the pre-commit hooks. Unless there is a good reason to do otherwise, please do not import the modules inside functions or classes. To deal with circular imports, we use the From c81dc564f6208bc2938365b58c0cf0a779d048dd Mon Sep 17 00:00:00 2001 From: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com> Date: Tue, 9 Sep 2025 17:30:44 +0200 Subject: [PATCH 8/8] Update docs/source/refs/contributing.rst Co-authored-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com> Signed-off-by: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com> --- docs/source/refs/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/refs/contributing.rst b/docs/source/refs/contributing.rst index 1bfd600e401..40c84619655 100644 --- a/docs/source/refs/contributing.rst +++ b/docs/source/refs/contributing.rst @@ -280,9 +280,9 @@ Similarly, within Python classes, we follow the following structure: # Instance methods (public) # Class methods (public) # Static methods (public) - # Instance methods (private) - # Class methods (private) - # Static methods (private) + # _Instance methods (private) + # _Class methods (private) + # _Static methods (private) The rule of thumb is that the functions within the classes are ordered in the way a user would expect to use them. For instance, if the class contains the method :meth:`initialize`, :meth:`reset`,