Adds new external project / internal task template generator (#2039)

# Description

This PR adds the implementation to generate Isaac Lab's external project
or internal task.

Just run `./isaaclab.sh --new` or `isaaclab.bat --new` (or `-n`) and let
yourself go!

## Type of change

- New feature (non-breaking change which adds functionality)
- This change requires a documentation update

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

<!--
As you go through the checklist above, you can mark something as done by
putting an x character in it

For example,
- [x] I have done this task
- [ ] I have not done this task
-->

---------

Signed-off-by: Toni-SM <[email protected]>
Signed-off-by: Kelly Guo <[email protected]>
Co-authored-by: Kelly Guo <[email protected]>

Author: Toni-SM

docs/source/overview/developer-guide/template.rst

@@ -1,57 +1,92 @@
-Building your Own Project
-=========================
+.. _template-generator:
+
+Build your Own Project or Task
+==============================
 
 Traditionally, building new projects that utilize Isaac Lab's features required creating your own
 extensions within the Isaac Lab repository. However, this approach can obscure project visibility and
-complicate updates from one version of Isaac Lab to another. To circumvent these challenges, we now
-provide a pre-configured and customizable `extension template <https://github.com/isaac-sim/IsaacLabExtensionTemplate>`_
-for creating projects in an isolated environment.
+complicate updates from one version of Isaac Lab to another. To circumvent these challenges,
+we now provide a command-line tool (**template generator**) for creating Isaac Lab-based projects and tasks.
 
-This template serves three distinct use cases:
+The template generator enables you to create an:
 
-* **Project Template**: Provides essential access to Isaac Sim and Isaac Lab's features, making it ideal for projects
-  that require a standalone environment.
-* **Python Package**: Facilitates integration with Isaac Sim's native or virtual Python environment, allowing for
-  the creation of Python packages that can be shared and reused across multiple projects.
-* **Omniverse Extension**: Supports direct integration into Omniverse extension workflow.
+* **External project** (recommended): An isolated project that is not part of the Isaac Lab repository. This approach
+  works outside of the core Isaac Lab repository, ensuring that your development efforts remain self-contained. Also,
+  it allows your code to be run as an extension in Omniverse.
 
-.. note::
+  .. hint::
+
+    For the external project, the template generator will initialize a new Git repository in the specified directory.
+    You can push the generated content to your own remote repository (e.g. GitHub) and share it with others.
+
+* **Internal task**: A task that is part of the Isaac Lab repository. This approach should only be used to create
+  new tasks within the Isaac Lab repository in order to contribute to it.
+
+Running the template generator
+------------------------------
+
+Install Isaac Lab by following the `installation guide <../../setup/installation/index.html>`_.
+We recommend using conda installation as it simplifies calling Python scripts from the terminal.
+
+Then, run the following command to generate a new external project or internal task:
+
+.. tab-set::
+  :sync-group: os
+
+  .. tab-item:: :icon:`fa-brands fa-linux` Linux
+      :sync: linux
 
-  We recommend using the extension template for new projects, as it provides a more streamlined and
-  efficient workflow. Additionally it ensures that your project remains up-to-date with the latest
-  features and improvements in Isaac Lab.
+      .. code-block:: bash
 
+        ./isaaclab.sh --new  # or "./isaaclab.sh -n"
 
-Installation
-------------
+  .. tab-item:: :icon:`fa-brands fa-windows` Windows
+      :sync: windows
 
-Install Isaac Lab by following the `installation guide <../../setup/installation/index.html>`_. We recommend using the conda installation as it simplifies calling Python scripts from the terminal.
+      .. code-block:: batch
+
+        isaaclab.bat --new  :: or "isaaclab.bat -n"
+
+The generator will guide you in setting up the project/task for your needs by asking you the following questions:
+
+* Type of project/task (external or internal), and project/task path or names according to the selected type.
+* Isaac Lab workflows (see :ref:`feature-workflows`).
+* Reinforcement learning libraries (see :ref:`rl-frameworks`), and algorithms (if the selected libraries support multiple algorithms).
+
+External project usage (once generated)
+---------------------------------------
+
+Once the external project is generated, a ``README.md`` file will be created in the specified directory.
+This file will contain instructions on how to install the project and run the tasks.
+
+Here are some general commands to get started with it:
+
+.. note::
 
-Clone the extension template repository separately from the Isaac Lab installation (i.e. outside the IsaacLab directory):
+  If Isaac Lab is not installed in a conda environment or in a (virtual) Python environment, use ``FULL_PATH_TO_ISAACLAB/isaaclab.sh -p``
+  (or ``FULL_PATH_TO_ISAACLAB\isaaclab.bat -p`` on Windows) instead of ``python`` to run the commands below.
 
-.. code:: bash
+* Install the project (in editable mode).
 
-	# Option 1: HTTPS
-	git clone https://github.com/isaac-sim/IsaacLabExtensionTemplate.git
+  .. code:: bash
 
-	# Option 2: SSH
-	git clone [email protected]:isaac-sim/IsaacLabExtensionTemplate.git
+    python -m pip install -e source/<given-project-name>
 
-Throughout the repository, the name ``ext_template`` only serves as an example and we provide a script to rename all the references to it automatically:
+* List the tasks available in the project.
 
-.. code:: bash
+  .. warning::
 
-	# Enter the repository
-	cd IsaacLabExtensionTemplate
+    If the task names change, it may be necessary to update the search pattern ``"Template-"``
+    (in the ``scripts/list_envs.py`` file) so that they can be listed.
 
-	# Rename all occurrences of ext_template (in files/directories) to your_fancy_extension_name
-	python scripts/rename_template.py your_fancy_extension_name
+  .. code:: bash
 
-Using a python interpreter that has Isaac Lab installed, install the library:
+    python scripts/list_envs.py
 
-.. code:: bash
+* Run a task.
 
-	python -m pip install -e source/ext_template
+  .. code:: bash
 
+    python scripts/<specific-rl-library>/train.py --task=<Task-Name>
 
-For more details, please follow the instructions in the `extension template repository <https://github.com/isaac-sim/IsaacLabExtensionTemplate>`_.
+For more details, please follow the instructions in the generated project's ``README.md`` file.

docs/source/overview/reinforcement-learning/rl_frameworks.rst

@@ -1,3 +1,5 @@
+.. _rl-frameworks:
+
 Reinforcement Learning Library Comparison
 =========================================
 

docs/source/setup/installation/binaries_installation.rst

@@ -203,7 +203,7 @@ Clone the Isaac Lab repository into your workspace:
 
             ./isaaclab.sh --help
 
-            usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-c] -- Utility to manage Isaac Lab.
+            usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
 
             optional arguments:
                -h, --help           Display the help content.
@@ -215,6 +215,7 @@ Clone the Isaac Lab repository into your workspace:
                -o, --docker         Run the docker container helper script (docker/container.sh).
                -v, --vscode         Generate the VSCode settings file from template.
                -d, --docs           Build the documentation from source using sphinx.
+               -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
@@ -224,7 +225,7 @@ Clone the Isaac Lab repository into your workspace:
 
             isaaclab.bat --help
 
-            usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage Isaac Lab.
+            usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
 
             optional arguments:
                -h, --help           Display the help content.
@@ -235,6 +236,7 @@ Clone the Isaac Lab repository into your workspace:
                -t, --test           Run all python unittest tests.
                -v, --vscode         Generate the VSCode settings file from template.
                -d, --docs           Build the documentation from source using sphinx.
+               -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
 
 

docs/source/setup/installation/isaaclab_pip_installation.rst

@@ -7,7 +7,7 @@ that are built on top of Isaac Lab. Isaac Lab pip packages **do not** include an
 training, inferencing, or running standalone workflows such as demos and examples. Therefore, users are required
 to define your own runner scripts when installing Isaac Lab from pip.
 
-To learn about how to set up your own extension project on top of Isaac Lab, visit `Extension Template <../../overview/developer-guide/template.html>`_.
+To learn about how to set up your own project on top of Isaac Lab, see :ref:`template-generator`.
 
 .. note::
 

docs/source/setup/installation/pip_installation.rst

@@ -211,7 +211,7 @@ Clone the Isaac Lab repository into your workspace:
 
             ./isaaclab.sh --help
 
-            usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-c] -- Utility to manage Isaac Lab.
+            usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
 
             optional arguments:
                -h, --help           Display the help content.
@@ -223,6 +223,7 @@ Clone the Isaac Lab repository into your workspace:
                -o, --docker         Run the docker container helper script (docker/container.sh).
                -v, --vscode         Generate the VSCode settings file from template.
                -d, --docs           Build the documentation from source using sphinx.
+               -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
@@ -232,7 +233,7 @@ Clone the Isaac Lab repository into your workspace:
 
             isaaclab.bat --help
 
-            usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage Isaac Lab.
+            usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
 
             optional arguments:
                -h, --help           Display the help content.
@@ -243,6 +244,7 @@ Clone the Isaac Lab repository into your workspace:
                -t, --test           Run all python unittest tests.
                -v, --vscode         Generate the VSCode settings file from template.
                -d, --docs           Build the documentation from source using sphinx.
+               -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
 
 Installation

isaaclab.bat

@@ -236,7 +236,7 @@ goto :eof
 rem Print the usage description
 :print_help
 echo.
-echo usage: %~nx0 [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Isaac Lab.
+echo usage: %~nx0 [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage extensions in Isaac Lab.
 echo.
 echo optional arguments:
 echo     -h, --help           Display the help content.
@@ -247,6 +247,7 @@ echo     -s, --sim            Run the simulator executable (isaac-sim.bat) provi
 echo     -t, --test           Run all python unittest tests.
 echo     -v, --vscode         Generate the VSCode settings file from template.
 echo     -d, --docs           Build the documentation from source using sphinx.
+echo     -n, --new            Create a new external project or internal task from template.
 echo     -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
 echo.
 goto :eof
@@ -463,6 +464,44 @@ if "%arg%"=="-i" (
     )
     !isaacsim_exe! --ext-folder %ISAACLAB_PATH%\source !allArgs1
     goto :end
+) else if "%arg%"=="-n" (
+    rem run the template generator script
+    call :extract_python_exe
+    set "allArgs="
+    for %%a in (%*) do (
+        REM Append each argument to the variable, skip the first one
+        if defined skip (
+            set "allArgs=!allArgs! %%a"
+        ) else (
+            set "skip=1"
+        )
+    )
+    echo [INFO] Installing template dependencies...
+    !python_exe! -m pip install -q -r tools\template\requirements.txt
+    echo.
+    echo [INFO] Running template generator...
+    echo.
+    !python_exe! tools\template\cli.py !allArgs!
+    goto :end
+) else if "%arg%"=="--new" (
+    rem run the template generator script
+    call :extract_python_exe
+    set "allArgs="
+    for %%a in (%*) do (
+        REM Append each argument to the variable, skip the first one
+        if defined skip (
+            set "allArgs=!allArgs! %%a"
+        ) else (
+            set "skip=1"
+        )
+    )
+    echo [INFO] Installing template dependencies...
+    !python_exe! -m pip install -q -r tools\template\requirements.txt
+    echo.
+    echo [INFO] Running template generator...
+    echo.
+    !python_exe! tools\template\cli.py !allArgs!
+    goto :end
 ) else if "%arg%"=="-t" (
     rem run the python provided by Isaac Sim
     call :extract_python_exe

isaaclab.sh

@@ -241,7 +241,7 @@ update_vscode_settings() {
 
 # print the usage description
 print_help () {
-    echo -e "\nusage: $(basename "$0") [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-c] -- Utility to manage Isaac Lab."
+    echo -e "\nusage: $(basename "$0") [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab."
     echo -e "\noptional arguments:"
     echo -e "\t-h, --help           Display the help content."
     echo -e "\t-i, --install [LIB]  Install the extensions inside Isaac Lab and learning frameworks as extra dependencies. Default is 'all'."
@@ -252,6 +252,7 @@ print_help () {
     echo -e "\t-o, --docker         Run the docker container helper script (docker/container.sh)."
     echo -e "\t-v, --vscode         Generate the VSCode settings file from template."
     echo -e "\t-d, --docs           Build the documentation from source using sphinx."
+    echo -e "\t-n, --new            Create a new external project or internal task from template."
     echo -e "\t-c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'."
     echo -e "\n" >&2
 }
@@ -375,6 +376,17 @@ while [[ $# -gt 0 ]]; do
             # exit neatly
             break
             ;;
+        -n|--new)
+            # run the template generator script
+            python_exe=$(extract_python_exe)
+            shift # past argument
+            echo "[INFO] Installing template dependencies..."
+            ${python_exe} -m pip install -q -r ${ISAACLAB_PATH}/tools/template/requirements.txt
+            echo -e "\n[INFO] Running template generator...\n"
+            ${python_exe} ${ISAACLAB_PATH}/tools/template/cli.py $@
+            # exit neatly
+            break
+            ;;
         -t|--test)
             # run the python provided by isaacsim
             python_exe=$(extract_python_exe)

scripts/reinforcement_learning/rl_games/play.py

@@ -67,6 +67,8 @@
 import isaaclab_tasks  # noqa: F401
 from isaaclab_tasks.utils import get_checkpoint_path, load_cfg_from_registry, parse_env_cfg
 
+# PLACEHOLDER: Extension template (do not remove this comment)
+
 
 def main():
     """Play with RL-Games agent."""

scripts/reinforcement_learning/rl_games/train.py

@@ -70,6 +70,8 @@
 import isaaclab_tasks  # noqa: F401
 from isaaclab_tasks.utils.hydra import hydra_task_config
 
+# PLACEHOLDER: Extension template (do not remove this comment)
+
 
 @hydra_task_config(args_cli.task, "rl_games_cfg_entry_point")
 def main(env_cfg: ManagerBasedRLEnvCfg | DirectRLEnvCfg | DirectMARLEnvCfg, agent_cfg: dict):

scripts/reinforcement_learning/rsl_rl/play.py

@@ -61,6 +61,8 @@
 import isaaclab_tasks  # noqa: F401
 from isaaclab_tasks.utils import get_checkpoint_path, parse_env_cfg
 
+# PLACEHOLDER: Extension template (do not remove this comment)
+
 
 def main():
     """Play with RSL-RL agent."""