[Docs] Upgrading docs (#516)

* version switchers

* update logo

* custom logos

* a lot of docs

* update docs for agent and add intersphinx mapping

* update pose docs

* work

* work

* fixes

* Update quickstart.md

* docs

docs/.gitignore

@@ -1 +1,2 @@
-build
+build
+source/user_guide/reference/_autosummary/

docs/source/_static/css/custom.css

@@ -0,0 +1,3 @@
+.logo__image { 
+  padding: 10px;
+}

docs/source/_static/version_switcher.json

@@ -0,0 +1,12 @@
+[
+  {
+    "version": "latest",
+    "url": "https://maniskill.readthedocs.io/en/latest/"
+  },
+  {
+    "name": "3.0.0b8 (stable)",
+    "version": "v3.0.0b8",
+    "url": "https://maniskill.readthedocs.io/en/v3.0.0b8/",
+    "preferred": true
+  }
+]

docs/source/_templates/class_no_parameters.rst

@@ -0,0 +1,28 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/conf.py

@@ -1,7 +1,9 @@
 import os
 import sys
+
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../../mani_skill"))
-__version__ = "3.0.0b8"
+import mani_skill
+__version__ = mani_skill.__version__
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -21,8 +23,11 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_subfigure",
@@ -37,26 +42,47 @@
 myst_heading_anchors = 4
 
 templates_path = ["_templates"]
-exclude_patterns = []
+# exclude_patterns = ["user_guide/reference/_autosummary/*"]
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "pydata_sphinx_theme"
+html_logo = "_static/logo_black.svg"
+html_favicon = "_static/favicon.svg"
+
+
+json_url = "https://maniskill.readthedocs.io/en/docs-upgrades/_static/version_switcher.json"
+version_match = "latest" #os.environ.get("READTHEDOCS_VERSION")
+release = __version__
+
 html_theme_options = {
     "use_edit_page_button": True,
     "icon_links": [
         {
             "name": "GitHub",
             "url": "https://github.com/haosulab/ManiSkill",
             "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Website",
+            "url": "https://maniskill.ai",
+            "icon": "fa-solid fa-globe",
         }
     ],
     "external_links": [
         {"name": "Changelog", "url": "https://github.com/haosulab/ManiSkill/releases"},
-    ]
-
+    ],
+    "logo": {
+        "image_dark": "_static/logo_white.svg",
+    },
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    "show_version_warning_banner": True,
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
 }
 html_context = {
     "display_github": True,
@@ -66,8 +92,18 @@
     "conf_py_path": "/source/",
     "doc_path": "docs/source"
 }
-
+html_css_files = [
+    'css/custom.css',
+]
 html_static_path = ['_static']
 
-autodoc_typehints = "description"
+### Autodoc configurations ###
+autodoc_typehints = "signature"
 autodoc_typehints_description_target = "all"
+autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']
+
+autosummary_generate = True
+
+# remove_from_toctrees = ["_autosummary/*"]
+
+intersphinx_mapping = {'gymnasium': ('https://gymnasium.farama.org/', None)}

docs/source/user_guide/datasets/demos.md

@@ -1,6 +1,6 @@
 # Demonstrations
 
-We provide a command line tool to download demonstrations directly from our [Hugging Face 🤗 dataset page](https://huggingface.co/datasets/haosulab/ManiSkill) which are done by task ID. The tool will download the demonstration files to a folder and also a few demonstration videos visualizing what the demonstrations look like. See [Tasks](../concepts/environments.md) for a list of all supported tasks.
+We provide a command line tool to download demonstrations directly from our [Hugging Face 🤗 dataset page](https://huggingface.co/datasets/haosulab/ManiSkill) which are done by task ID. The tool will download the demonstration files to a folder and also a few demonstration videos visualizing what the demonstrations look like. See [Tasks](../../tasks/index.md) for a list of all supported tasks.
 
 <!-- TODO: add a table here detailing the data info in detail -->
 <!-- Please see our [notes](https://docs.google.com/document/d/1bBKmsR-R_7tR9LwaT1c3J26SjIWw27tWSLdHnfBR01c/edit?usp=sharing) about the details of the demonstrations. -->

docs/source/user_guide/getting_started/quickstart.md

@@ -5,7 +5,7 @@ ManiSkill is a robotics simulator built on top of SAPIEN. It provides a standard
 
 ## Interface
 
-Here is a basic example of how to run a ManiSkill task following the interface of [Gymnasium](https://gymnasium.farama.org/) and execute a random policy.
+Here is a basic example of how to run a ManiSkill task following the interface of [Gymnasium](https://gymnasium.farama.org/) and execute a random policy with a few basic options
 
 ```python
 import gymnasium as gym
@@ -31,15 +31,15 @@ while not done:
 env.close()
 ```
 
-Changing `num_envs` to a value > 1 will automatically turn on the GPU simulation mode. More quick details [covered below](#gpu-parallelizedvectorized-tasks). You will also notice that all data returned is a batched torch tensor. To have the exact same API defined by [gym/gymnasium](https://gymnasium.farama.org/) see the section on [reinforcement learning setups](../reinforcement_learning/setup.md)
+Changing `num_envs` to a value > 1 will automatically turn on the GPU simulation mode. More quick details [covered below](#gpu-parallelizedvectorized-tasks).
 
-You can also run the same code from the command line to demo random actions
+You can also run the same code from the command line to demo random actions and play with rendering options
 
 ```bash
 # run headless / without a display
 python -m mani_skill.examples.demo_random_action -e PickCube-v1
-# run with A GUI
-python -m mani_skill.examples.demo_random_action -e PickCube-v1 --render-mode="human"
+# run with A GUI and ray tracing
+python -m mani_skill.examples.demo_random_action -e PickCube-v1 --render-mode="human" --shader="rt-fast"
 ```
 
 Running with `render_mode="human"` will open up a GUI shown below that you can use to interactively explore the scene, pause/play the script, teleport objects around, and more.
@@ -49,7 +49,7 @@ Running with `render_mode="human"` will open up a GUI shown below that you can u
 alt: SAPIEN GUI showing the PickCube task
 ---
 ```
-
+<!-- 
 We also have demos for simulations of more interesting scenes like ReplicaCAD, which can be run by doing
 
 ```bash
@@ -67,21 +67,23 @@ python -m mani_skill.examples.demo_random_action -e "ReplicaCAD_SceneManipulatio
 
 <video preload="auto" controls="True" width="100%">
 <source src="https://github.com/haosulab/ManiSkill/raw/main/docs/source/_static/videos/fetch_random_action_replica_cad_rt.mp4" type="video/mp4">
-</video>
-
+</video> -->
 
-You may notice that everything returned by the environment is a torch Tensor and has a batch dimension with value 1. To reduce extra code handling numpy vs torch, cpu vs gpu sim, everything in ManiSkill defaults to serving/using batched torch Tensors of all data. To change the environment to serve numpy, unbatched data simply do the following
+You will also notice that all data returned is a batched torch tensor. To reduce extra code handling numpy vs torch, cpu vs gpu sim, everything in ManiSkill defaults to serving/using batched torch Tensors of all data. To change the environment to serve numpy, unbatched data simply do the following
 
 ```python
 from mani_skill.utils.wrappers.gymnasium import CPUGymWrapper
-env = gym.make(env_id)
+env = gym.make(env_id, num_envs=1)
 env = CPUGymWrapper(env)
 obs, _ = env.reset() # obs is numpy and unbatched
 ```
 
+To have the exact same API defined by [gym/gymnasium](https://gymnasium.farama.org/) for single/vectorized environments see the section on [reinforcement learning setups](../reinforcement_learning/setup.md).
+
 For a compilation of demos you can run without having to write any extra code check out the [demos page](../demos/index)
 
-For the full documentation of options you can provide for gym.make see the [docstring in our repo](https://github.com/haosulab/ManiSkill/blob/main/mani_skill/envs/sapien_env.py)
+See {py:class}`mani_skill.envs.sapien_env` for the full list of environment instantiation options.
+
 
 
 ## GPU Parallelized/Vectorized Tasks
@@ -153,6 +155,10 @@ env = gym.make(
     parallel_in_single_scene=True,
     viewer_camera_configs=dict(shader_pack="rt-fast"),
 )
+env.reset()
+while True:
+    env.step(env.action_space.sample())
+    env.render_human()
 ```
 
 This will then open up a GUI that looks like so:
@@ -167,14 +173,16 @@ We currently do not properly support exposing multiple visible CUDA devices to a
 
 ## Task Instantiation Options
 
+For the full list of environment instantiation options see {py:class}`mani_skill.envs.sapien_env`. Here we list some common options:
+
 
 Each ManiSkill task supports different **observation modes** and **control modes**, which determine its **observation space** and **action space**. They can be specified by `gym.make(env_id, obs_mode=..., control_mode=...)`.
 
 The common observation modes are `state`, `rgbd`, `pointcloud`. We also support `state_dict` (states organized as a hierarchical dictionary) and `sensor_data` (raw visual observations without postprocessing). Please refer to [Observation](../concepts/observation.md) for more details. Furthermore, visual data generated by the simulator can be modified in many ways via shaders. Please refer to [the sensors/cameras tutorial](../tutorials/sensors/index.md) for more details.
 
 We support a wide range of controllers. Different controllers can have different effects on your algorithms. Thus, it is recommended to understand the action space you are going to use. Please refer to [Controllers](../concepts/controllers.md) for more details.
 
-Some tasks require **downloading assets** that are not stored in the python package itself. You can download task-specific assets by `python -m mani_skill.utils.download_asset ${ENV_ID}`. The assets will be downloaded to `~/maniskill/data` by default, but you can also use the environment variable `MS_ASSET_DIR` to change this destination. Please refer to [Tasks](../../tasks/index.md) for all tasks built in out of the box, and which tasks require downloading assets.
+Some tasks require **downloading assets** that are not stored in the python package itself. You can download task-specific assets by `python -m mani_skill.utils.download_asset ${ENV_ID}`. The assets will be downloaded to `~/maniskill/data` by default, but you can also use the environment variable `MS_ASSET_DIR` to change this destination. If you don't download assets ahead of the time you will be prompted to do so if they are missing when running an environment.
 
 Some ManiSkill tasks also support swapping robot embodiments such as the `PickCube-v1` task. You can try using the fetch robot instead by running
 

docs/source/user_guide/reference/index.md

@@ -7,9 +7,7 @@ Subpackages:
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
-   
-mani_skill.envs.sapien_env
+:glob:
+*
 
-mani_skill.utils.common
-mani_skill.utils.sapien_utils
 ```

docs/source/user_guide/reference/mani_skill.agent.base_agent.md

@@ -0,0 +1,8 @@
+# `mani_skill.agents.base_agent`
+
+```{eval-rst}  
+.. automodule:: mani_skill.agents.base_agent
+    :members:
+    :show-inheritance:
+    :undoc-members:
+```

docs/source/user_guide/reference/mani_skill.envs.sapien_env.md

@@ -1,6 +1,10 @@
-# mani_skill.envs.sapien_env
+# `mani_skill.envs.sapien_env`
+
+The BaseEnv class is the class you should inherit from if you want to create a new environment/task. The arguments here also describe all the possible run-time arguments you can pass when creating environments via `gym.make`.
 
 ```{eval-rst}  
 .. automodule:: mani_skill.envs.sapien_env
     :members:
+    :show-inheritance:
+    :undoc-members:
 ```

docs/source/user_guide/reference/mani_skill.envs.scene.md

@@ -0,0 +1,10 @@
+# `mani_skill.envs.scene`
+
+The ManiSkillScene class manages most of the underlying data for a ManiSkill environment. It is created each time an environment is instantiated or reconfigured and can be accessed via `env.scene` where `env` is your created environment object.
+
+```{eval-rst}  
+.. automodule:: mani_skill.envs.scene
+    :members:
+    :show-inheritance:
+    :undoc-members:
+```

docs/source/user_guide/reference/mani_skill.sensors.rst

@@ -0,0 +1,15 @@
+``mani_skill.sensors`` module
+===================================
+
+
+.. currentmodule:: mani_skill.sensors.base_sensor
+
+.. automodule:: mani_skill.sensors.base_sensor
+    :members:
+    :undoc-members:
+
+.. currentmodule:: mani_skill.sensors.camera
+
+.. automodule:: mani_skill.sensors.camera
+    :members:
+    :undoc-members:

docs/source/user_guide/reference/mani_skill.utils.common.rst

@@ -0,0 +1,10 @@
+``mani_skill.utils.common`` module
+===================================
+
+.. currentmodule:: mani_skill.utils.common
+
+.. automodule:: mani_skill.utils.common
+    :members:
+    :undoc-members:
+
+    .. rubric:: Functions