Updates the docs to latest sphinx version (#190)

# Description

This MR does the following:

* Addresses some of the build issues related to docs and migrates to the latest sphinx
* Also updates the API references

## Type of change

- New feature (non-breaking change which adds functionality)

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./orbit.sh --format`
- [x] 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

.github/workflows/docs.yaml

@@ -15,7 +15,7 @@ jobs:
     - name: Setup python
       uses: actions/setup-python@v2
       with:
-        python-version: "3.8"
+        python-version: "3.10"
         architecture: x64
 
     - name: Install dev requirements

.gitignore

@@ -35,6 +35,10 @@
 docker/artifacts/
 *.tmp
 
+# Doc Outputs
+**/docs/_build/*
+**/generated/*
+
 # Isaac-Sim packman
 _isaac_sim*
 _repo

CONTRIBUTORS.md

@@ -25,6 +25,7 @@ Guidelines for modifications:
 * James Smith
 * **Mayank Mittal** (maintainer)
 * Nikita Rudin
+* Pascal Roth
 
 ## Contributors
 
@@ -37,7 +38,6 @@ Guidelines for modifications:
 * Jingzhou Liu
 * Kourosh Darvish
 * Qinxi Yu
-* Pascal Roth
 * René Zurbrügg
 * Ritvik Singh
 * Rosario Scalise

README.md

@@ -4,16 +4,19 @@
 
 # Orbit
 
-[![IsaacSim](https://img.shields.io/badge/Isaac%20Sim-2022.2.0-orange.svg)](https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/overview.html)
-[![Python](https://img.shields.io/badge/python-3.7-blue.svg)](https://docs.python.org/3/whatsnew/3.7.html)
-[![Linux platform](https://img.shields.io/badge/platform-linux--64-lightgrey.svg)](https://releases.ubuntu.com/20.04/)
+[![IsaacSim](https://img.shields.io/badge/IsaacSim-2023.1.0--hotfix.1-silver.svg)](https://docs.omniverse.nvidia.com/isaacsim/latest/overview.html)
+[![Python](https://img.shields.io/badge/python-3.10-blue.svg)](https://docs.python.org/3/whatsnew/3.10.html)
+[![Linux platform](https://img.shields.io/badge/platform-linux--64-orange.svg)](https://releases.ubuntu.com/20.04/)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
 [![Docs status](https://img.shields.io/badge/docs-passing-brightgreen.svg)](https://isaac-orbit.github.io/orbit)
 [![License](https://img.shields.io/badge/license-BSD--3-yellow.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
 <!-- TODO: Replace docs status with workflow badge? Link: https://github.com/isaac-orbit/orbit/actions/workflows/docs.yaml/badge.svg -->
 
-Orbit is a unified and modular framework for robot learning powered by [NVIDIA Isaac Sim](https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/overview.html). It offers a modular design to easily and efficiently create robotic environments with photo-realistic scenes, and fast and accurate simulation.
+**Orbit** is a unified and modular framework for robot learning that aims to simplify common workflows
+in robotics research (such as RL, learning from demonstrations, and motion planning). It is built upon
+[NVIDIA Isaac Sim](https://docs.omniverse.nvidia.com/isaacsim/latest/overview.html) to leverage the latest
+simulation capabilities for photo-realistic scenes, and fast and accurate simulation.
 
 Please refer our [documentation page](https://isaac-orbit.github.io/orbit) to learn more about the installation steps, features and tutorials.
 
@@ -37,13 +40,13 @@ For issues related to Isaac Sim, we recommend checking its [documentation](https
 
 NVIDIA Isaac Sim is available freely under [individual license](https://www.nvidia.com/en-us/omniverse/download/). For more information about its license terms, please check [here](https://docs.omniverse.nvidia.com/app_isaacsim/common/NVIDIA_Omniverse_License_Agreement.html#software-support-supplement).
 
-ORBIT framework is released under [BSD-3 License](LICENSE). The license files of its dependencies and assets are present in the [`docs/licenses`](docs/licenses) directory.
+Orbit framework is released under [BSD-3 License](LICENSE). The license files of its dependencies and assets are present in the [`docs/licenses`](docs/licenses) directory.
 
 ## Citation
 
 Please cite [this paper](https://arxiv.org/abs/2301.04195) if you use this framework in your work:
 
-```
+```text
 @article{mittal2023orbit,
    author={Mittal, Mayank and Yu, Calvin and Yu, Qinxi and Liu, Jingzhou and Rudin, Nikita and Hoeller, David and Yuan, Jia Lin and Singh, Ritvik and Guo, Yunrong and Mazhar, Hammad and Mandlekar, Ajay and Babich, Buck and State, Gavriel and Hutter, Marco and Garg, Animesh},
    journal={IEEE Robotics and Automation Letters},

docs/conf.py

@@ -26,29 +26,31 @@
 # -- Project information -----------------------------------------------------
 
 project = "orbit"
-copyright = "2022, NVIDIA, ETH Zurich and University of Toronto"
-author = "NVIDIA, ETH Zurich and University of Toronto"
+copyright = "2022-2023, The ORBIT Project Developers."
+author = "The ORBIT Project Developers."
 
-version = "0.1.0"
+version = "0.2.0"
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    "autodocsumm",
+    "myst_parser",
     "sphinx.ext.napoleon",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.intersphinx",
+    "sphinxemoji.sphinxemoji",
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "sphinxcontrib.bibtex",
-    "myst_parser",
-    "autodocsumm",
     "sphinx_copybutton",
-    "sphinx_panels",
+    "sphinx_design",
 ]
 
 # mathjax hacks
@@ -69,17 +71,22 @@
     ".md": "markdown",
 }
 
-# put type hints inside the description instead of the signature (easier to read)
-autodoc_typehints = "description"
-autodoc_typehints_description_target = "documented"
+# put type hints inside the signature instead of the description (easier to maintain)
+autodoc_typehints = "signature"
+# autodoc_typehints_format = "fully-qualified"
 # document class *and* __init__ methods
 autoclass_content = "class"  #
 # separate class docstring from __init__ docstring
 autodoc_class_signature = "separated"
 # sort members by source order
-autodoc_member_order = "groupwise"
+autodoc_member_order = "bysource"
+# inherit docstrings from base classes
+autodoc_inherit_docstrings = True
 # BibTeX configuration
 bibtex_bibfiles = ["source/_static/refs.bib"]
+# generate autosummary even if no references
+autosummary_generate = True
+autosummary_generate_overwrite = False
 # default autodoc settings
 autodoc_default_options = {
     "autosummary": True,
@@ -88,8 +95,10 @@
 # generate links to the documentation of objects in external projects
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "numpy": ("http://docs.scipy.org/doc/numpy", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
     "torch": ("https://pytorch.org/docs/stable/", None),
+    "isaac": ("https://docs.omniverse.nvidia.com/py/isaacsim", None),
+    "gymnasium": ("https://gymnasium.farama.org/", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -112,6 +121,8 @@
     "omni.kit",
     "omni.usd",
     "omni.client",
+    "omni.physx",
+    "omni.physics",
     "pxr.PhysxSchema",
     "pxr.PhysicsSchemaTools",
     "omni.replicator",
@@ -120,6 +131,10 @@
     "omni.isaac.cloner",
     "omni.isaac.urdf",
     "omni.isaac.version",
+    "omni.isaac.motion_generation",
+    "omni.isaac.ui",
+    "omni.timeline",
+    "omni.ui",
     "gym",
     "skrl",
     "stable_baselines3",
@@ -156,47 +171,74 @@
     "ref.python",
 ]
 
+# -- Internationalization ----------------------------------------------------
+
+# specifying the natural language populates some key tags
+language = "en"
+
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 import sphinx_book_theme
 
+html_title = "orbit documentation"
 html_theme_path = [sphinx_book_theme.get_html_theme_path()]
 html_theme = "sphinx_book_theme"
-html_logo = "source/_static/nv-logo.png"
 html_favicon = "source/_static/favicon.ico"
+html_show_copyright = True
+html_show_sphinx = False
+html_last_updated_fmt = ""  # to reveal the build date in the pages meta
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["source/_static"]
-html_css_files = ["css/nvidia.css"]
+html_static_path = ["source/_static/css"]
+html_css_files = ["custom.css"]
 
 html_theme_options = {
     "collapse_navigation": True,
     "repository_url": "https://github.com/NVIDIA-Omniverse/Orbit",
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,
-    "show_toc_level": 2,
+    "show_toc_level": 1,
     "use_sidenotes": True,
-    "announcement": (
-        "⚠️This is a pre-release version of Orbit. Please report any issues on <a"
-        " href='https://github.com/NVIDIA-Omniverse/orbit/issues'>GitHub</a>."
-    ),
+    "logo": {
+        "text": f"orbit documentation",
+        "image_light": "source/_static/NVIDIA-logo-white.png",
+        "image_dark": "source/_static/NVIDIA-logo-black.png",
+    },
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/NVIDIA-Omniverse/Orbit",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Isaac Sim",
+            "url": "https://developer.nvidia.com/isaac-sim",
+            "icon": "https://img.shields.io/badge/IsaacSim-2023.1.0-silver.svg",
+            "type": "url",
+        },
+        {
+            "name": "Stars",
+            "url": "https://img.shields.io/github/stars/NVIDIA-Omniverse/Orbit?color=fedcba",
+            "icon": "https://img.shields.io/github/stars/NVIDIA-Omniverse/Orbit?color=fedcba",
+            "type": "url",
+        },
+    ],
+    "icon_links_label": "Quick Links",
 }
 
-html_show_copyright = True
-html_show_sphinx = False
+html_sidebars = {"**": ["navbar-logo.html", "icon-links.html", "search-field.html", "sbt-sidebar-nav.html"]}
 
 
 # -- Advanced configuration -------------------------------------------------
 
 
 def skip_member(app, what, name, obj, skip, options):
-    exclusions = ["from_dict", "to_dict", "replace"]  # List the names of the functions you want to skip here
+    # List the names of the functions you want to skip here
+    exclusions = ["from_dict", "to_dict", "replace", "copy", "__post_init__"]
     if name in exclusions:
         return True
     return None

docs/index.rst

@@ -1,34 +1,25 @@
 Overview
 ========
 
-**Isaac Orbit** (or *orbit* in short) is a unified and modular framework, built on top of `NVIDIA
-Omniverse <https://docs.omniverse.nvidia.com/>`__ and `Isaac
-Sim <https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/overview.html>`__,
-for robot learning. It offers a modular design to easily and efficiently
-create robot learning environments with photo-realistic scenes, and fast
-and efficient simulation.
+**Orbit** is a unified and modular framework for robot learning that aims to simplify common workflows
+in robotics research (such as RL, learning from demonstrations, and motion planning). It is built upon
+`NVIDIA Isaac Sim` to leverage the latest simulation capabilities for photo-realistic scenes, and fast
+and efficient simulation. The core objectives of the framework are:
+
+- **Modularity**: Easily customize and add new environments, robots, and sensors.
+- **Agility**: Adapt to the changing needs of the community.
+- **Openness**: Remain open-sourced to allow the community to contribute and extend the framework.
+- **Battery-included**: Include a number of environments, sensors, and tasks that are ready to use.
+
+For more information about the framework, please refer to the `paper <https://arxiv.org/abs/2301.04195>`_
+:cite:`mittal2023orbit`. For clarifications on NVIDIA Isaac ecosystem, please check out the
+:doc:`/source/refs/faq` section.
 
 .. figure:: source/_static/tasks.jpg
    :width: 100%
    :alt: Example tasks created using orbit
 
 
-If you use ``orbit`` in your work, please cite the `paper <https://arxiv.org/abs/2301.04195>`_
-:cite:`mittal2023orbit` using the following BibTeX entry:
-
-.. code-block:: bibtex
-
-   @article{mittal2023orbit,
-      author={Mittal, Mayank and Yu, Calvin and Yu, Qinxi and Liu, Jingzhou and Rudin, Nikita and Hoeller, David and Yuan, Jia Lin and Singh, Ritvik and Guo, Yunrong and Mazhar, Hammad and Mandlekar, Ajay and Babich, Buck and State, Gavriel and Hutter, Marco and Garg, Animesh},
-      journal={IEEE Robotics and Automation Letters},
-      title={Orbit: A Unified Simulation Framework for Interactive Robot Learning Environments},
-      year={2023},
-      volume={8},
-      number={6},
-      pages={3740-3747},
-      doi={10.1109/LRA.2023.3270034}
-   }
-
 .. toctree::
    :maxdepth: 2
    :caption: Getting Started
@@ -80,7 +71,6 @@ If you use ``orbit`` in your work, please cite the `paper <https://arxiv.org/abs
    source/refs/troubleshooting
    source/refs/issues
    source/refs/changelog
-   source/refs/roadmap
    source/refs/license
    source/refs/bibliography
 
@@ -91,3 +81,5 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. _NVIDIA Isaac Sim: https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/overview.html

docs/requirements.txt

@@ -1,15 +1,15 @@
 # for building the docs
-importlib-metadata==4.11.3
-Jinja2==3.0.3
-Sphinx==4.5.0
-sphinx-book-theme==0.3.3
-myst-parser==0.18.1
-sphinxcontrib-bibtex==2.5.0
-autodocsumm==0.2.9
+sphinx-book-theme==1.0.1
+myst-parser
+sphinxcontrib-bibtex
+autodocsumm
 sphinx-copybutton
-sphinx-panels
+sphinx_design
+sphinxemoji
 
 # basic python
 numpy
 matplotlib
 warp-lang
+# learning
+gymnasium