Adds support for conda environment (#42)

* adds creating conda envronment using orbit.sh (-c)
* fixes running of formatter in orbit.sh (-f)
* adds docs building to orbit.sh (-d)
* updates docs with orbit.sh help, vscode instructions and state machine sample

.vscode/launch.json

@@ -14,7 +14,6 @@
                 "EXP_PATH": "${workspaceFolder}/_isaac_sim/apps",
                 "RESOURCE_NAME": "IsaacSim"
             },
-            "python": "${workspaceFolder}/_isaac_sim/kit/python/bin/python3",
             "envFile": "${workspaceFolder}/.vscode/.python.env",
             "preLaunchTask": "setup_python_env"
         },

.vscode/tasks.json

@@ -4,6 +4,7 @@
     "version": "2.0.0",
     "tasks": [
         {
+            // setup python env
             "label": "setup_python_env",
             "type": "shell",
             "linux": {
@@ -11,6 +12,7 @@
             }
         },
         {
+            // run formatter
             "label": "run_formatter",
             "type": "shell",
             "linux": {

.vscode/tools/setup_vscode.py

@@ -13,6 +13,7 @@ when the "setup_python_env.sh" is run as part of the vs-code launch configuratio
 """
 
 import re
+import sys
 import os
 import pathlib
 
@@ -23,16 +24,25 @@ ISAACSIM_DIR = os.path.join(ORBIT_DIR, "_isaac_sim")
 """Path to the isaac-sim directory."""
 
 
-def main():
+def overwrite_python_analysis_extra_paths(orbit_settings: str) -> str:
+    """Overwrite the python.analysis.extraPaths in the orbit settings file with the path names
+    from the isaac-sim settings file.
+
+    Args:
+        orbit_settings (str): The settings string to use as template.
+
+    Returns:
+        The settings string with overwritten python analysis extra paths.
+    """
     # isaac-sim settings
     isaacsim_vscode_filename = os.path.join(ISAACSIM_DIR, ".vscode", "settings.json")
     # make sure the isaac-sim settings file exists
     if not os.path.exists(isaacsim_vscode_filename):
         raise FileNotFoundError(f"Could not find the isaac-sim settings file: {isaacsim_vscode_filename}")
+
     # read the path names from the isaac-sim settings file
     with open(isaacsim_vscode_filename) as f:
         vscode_settings = f.read()
-
     # extract the path names
     # search for the python.analysis.extraPaths section and extract the contents
     settings = re.search(r"\"python.analysis.extraPaths\": \[.*?\]", vscode_settings, flags=re.MULTILINE | re.DOTALL)
@@ -46,6 +56,45 @@ def main():
     # combine them into a single string
     path_names = ",\n\t\t".expandtabs(4).join(path_names)
 
+    # replace the path names in the orbit settings file with the path names from the isaac-sim settings file
+    orbit_settings = re.sub(
+        r"\"python.analysis.extraPaths\": \[.*?\]",
+        '"python.analysis.extraPaths": [\n\t\t'.expandtabs(4) + path_names + "\n\t]".expandtabs(4),
+        orbit_settings,
+        flags=re.DOTALL,
+    )
+    # return the orbit settings string
+    return orbit_settings
+
+
+def overwrite_default_python_interpreter(orbit_settings: str) -> str:
+    """Overwrite the default python interpreter in the orbit settings file with the path to the
+    python interpreter used.
+
+    Args:
+        orbit_settings (str): The settings string to use as template.
+
+    Returns:
+        The settings string with overwritten default python interpreter.
+    """
+    # read executble name
+    python_exe = sys.executable
+    # if python interpreter is from conda, use that. Otherwise, use the template.
+    if "conda" not in python_exe:
+        return orbit_settings
+    # replace the default python interpreter in the orbit settings file with the path to the
+    # python interpreter in the orbit directory
+    orbit_settings = re.sub(
+        r"\"python.defaultInterpreterPath\": \".*?\"",
+        f'"python.defaultInterpreterPath": "{python_exe}"',
+        orbit_settings,
+        flags=re.DOTALL,
+    )
+    # return the orbit settings file
+    return orbit_settings
+
+
+def main():
     # orbit template settings
     orbit_vscode_template_filename = os.path.join(ORBIT_DIR, ".vscode", "tools", "settings.template.json")
     # make sure the orbit template settings file exists
@@ -54,13 +103,13 @@ def main():
     # read the orbit template settings file
     with open(orbit_vscode_template_filename) as f:
         orbit_template_settings = f.read()
-    # replace the path names in the orbit settings file with the path names from the isaac-sim settings file
-    orbit_settings = re.sub(
-        r"\"python.analysis.extraPaths\": \[.*?\]",
-        '"python.analysis.extraPaths": [\n\t\t'.expandtabs(4) + path_names + "\n\t]".expandtabs(4),
-        orbit_template_settings,
-        flags=re.DOTALL,
-    )
+
+    # overwrite the python.analysis.extraPaths in the orbit settings file with the path names
+    orbit_settings = overwrite_python_analysis_extra_paths(orbit_template_settings)
+    # overwrite the default python interpreter in the orbit settings file
+    # NOTE: thisis disabled since we don't need it. The default interpreter should always be the one from isaac-sim
+    # orbit_settings = overwrite_default_python_interpreter(orbit_settings)
+
     # add template notice to the top of the file
     header_message = (
         "// This file is a template and is automatically generated by the setup_vscode.py script.\n"

docs/requirements.txt

 # for building the docs
+importlib-metadata==4.11.3
 Jinja2==3.0.3
 Sphinx==4.5.0
 sphinx-book-theme==0.3.3

docs/source/setup/developer.rst

@@ -29,7 +29,7 @@ To setup the IDE, please follow these instructions:
 1. Open the ``orbit`` directory on Visual Studio Code IDE
 2. Run VSCode
    `Tasks <https://code.visualstudio.com/docs/editor/tasks>`__, by
-   pressing **``Ctrl+Shift+P``**, selecting ``Tasks: Run Task`` and
+   pressing ``Ctrl+Shift+P``, selecting ``Tasks: Run Task`` and
    running the ``setup_python_env`` in the drop down menu.
 
    .. image:: ../_static/vscode_tasks.png
@@ -50,19 +50,27 @@ following links:
 * `Debugging with VSCode <https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/tutorial_advanced_python_debugging.html>`__
 
 
-.. note::
+Configuring the python interpreter
+----------------------------------
+
+In the provided configuration, we set the default python interpreter to use the
+python executable provided by Omniverse. This is specified in the
+``.vscode/settings.json`` file:
 
-   In the provided configuration, we set the default python interpreter to use the
-   python executable provided by Omniverse. This is specified in the
-   ``.vscode/settings.json`` file:
+.. code-block:: json
 
-   .. code-block:: json
+   {
+      "python.defaultInterpreterPath": "${workspaceFolder}/_isaac_sim/kit/python/bin/python3",
+      "python.envFile": "${workspaceFolder}/.vscode/.python.env",
+   }
 
-      {
-         "python.defaultInterpreterPath": "${workspaceFolder}/_isaac_sim/kit/python/bin/python3",
-         "python.envFile": "${workspaceFolder}/.vscode/.python.env",
-      }
+If you want to use a different python interpreter (for instance, from your conda environment),
+you need to change the python interpreter used by selecting and activating the python interpreter
+of your choice in the bottom left corner of VSCode, or opening the command palette (``Ctrl+Shift+P``)
+and selecting ``Python: Select Interpreter``.
 
+For more information on how to set python interpreter for VSCode, please
+refer to the `VSCode documentation <https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters>`_.
 
 Repository organization
 -----------------------

docs/source/setup/installation.rst

@@ -130,43 +130,70 @@ Organizing the workspace
       # create a symbolic link
       ln -s ${ISAACSIM_PATH} _isaac_sim
 
-Building extensions
-~~~~~~~~~~~~~~~~~~~
-
-We provide a helper executable ```orbit.sh`` <orbit.sh>`__ that provides
+We provide a helper executable `orbit.sh <https://github.com/NVIDIA-Omniverse/Orbit/blob/main/orbit.sh>`_ that provides
 utilities to manage extensions:
 
-.. code:: bash
+.. code:: text
 
    ./orbit.sh --help
 
-   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-v] -- Utility to manage extensions in Isaac Orbit.
+   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Orbit.
 
    optional arguments:
-       -h, --help       Display the help content.
-       -i, --install    Install the extensions inside Isaac Orbit.
-       -e, --extra      Install extra dependencies such as the learning frameworks.
-       -f, --format     Run pre-commit to format the code and check lints.
-       -p, --python     Run the python executable (python.sh) provided by Isaac Sim.
-       -s, --sim        Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
-       -v, --vscode     Generate the VSCode settings file from template.
-
-The executable automatically fetches the python bundled with Isaac
-Sim, using ``./orbit.sh -p`` command. To not restrict running commands
-only from the top of this repository (where the README.md is located),
-we recommend adding the executable to your environment variables in
-your ``.bashrc`` or ``.zshrc`` file as an alias command. This can be
-achieved running the following on your terminal:
-
+      -h, --help           Display the help content.
+      -i, --install        Install the extensions inside Isaac Orbit.
+      -e, --extra          Install extra dependencies such as the learning frameworks.
+      -f, --format         Run pre-commit to format the code and check lints.
+      -p, --python         Run the python executable (python.sh) provided by Isaac Sim.
+      -s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
+      -v, --vscode         Generate the VSCode settings file from template.
+      -d, --docs           Build the documentation from source using sphinx.
+      -c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'.
+
+To not restrict running commands only from the top of this repository
+(where the README.md is located), we recommend adding the executable to your environment
+variables in your ``.bashrc`` or ``.zshrc`` file as an alias command. This can be achieved
+running the following on your terminal:
 
 .. code:: bash
 
    # note: execute the command from where the `orbit.sh` executable exists
-   # for bash users
+   # option1: for bash users
    echo -e "alias orbit=$(pwd)/orbit.sh" >> ${HOME}/.bashrc
-   # for zshell users
+   # option2: for zshell users
    echo -e "alias orbit=$(pwd)/orbit.sh" >> ${HOME}/.zshrc
 
+Setting up the environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The executable ``orbit.sh`` automatically fetches the python bundled with Isaac
+Sim, using ``./orbit.sh -p`` command (unless inside a virtual environment). This executable
+behaves like a python executable, and can be used to run any python script or
+module with the simulator. For more information, please refer to the
+`documentation <https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/install_python.html>`__.
+
+Although using a virtual environment is optional, we recommend using ``conda``. To install
+``conda``, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`__.
+In case you want to use ``conda`` to create a virtual environment, you can
+use the following command:
+
+.. code:: bash
+
+   ./orbit.sh --conda  # or `./orbit.sh -c`
+
+
+.. note::
+
+      If you are using ``conda`` to create a virtual environment, make sure to
+      activate the environment before running any scripts. For example:
+
+      .. code:: bash
+
+         conda activate orbit
+
+
+Building extensions
+~~~~~~~~~~~~~~~~~~~
 
 To build all the extensions, run the following commands:
 

docs/source/setup/sample.rst

@@ -73,6 +73,20 @@ useful to ensure that the environments are configured correctly.
 
       ./orbit.sh -p source/standalone/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 32
 
+
+State machine
+~~~~~~~~~~~~~
+
+We include examples on hand-crafted state machines for the environments. These
+help in understanding the environment and how to use the provided interfaces.
+The state machines are written in `warp <https://github.com/NVIDIA/warp>`__ which
+allows efficient execution for large number of environments using CUDA kernels.
+
+.. code:: bash
+
+   ./orbit.sh -p source/standalone/environments/state_machine/play_lift.py --num_envs 32
+
+
 Teleoperation
 ~~~~~~~~~~~~~