new theme and work

docs/source/conf.py

@@ -10,6 +10,7 @@
 copyright = "2024, ManiSkill3 Contributors"
 author = "ManiSkill3 Contributors"
 release = "3.0.0"
+version = "3.0.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -18,6 +19,7 @@
     "sphinx_rtd_theme",
     "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_subfigure",
@@ -35,7 +37,7 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "furo"
+html_theme = "sphinx_book_theme"
 # html_static_path = ["_static"]
 
 # replace "view page source" with "edit on github" in Read The Docs theme
@@ -45,4 +47,4 @@
     "github_user": "haosulab",
     "github_repo": "ManiSkill2",
     "github_version": "main/docs/source/",
-}
+}

docs/source/tutorials/custom_environments.md

@@ -10,6 +10,8 @@ To build a custom environment/task in ManiSkill, it is comprised of the followin
 4. (Optional) Dense/shaped reward function
 5. (Optional) Setting up cameras/sensors for observations and rendering/recording
 
+This tutorial will first cover each of the core components, and then showcase 3 different tutorial tasks ([PushCube](#example-task-1-push-cube), [PickSingleYCB](#example-task-2-pick-single-ycb), [OpenCabinetDrawer](#example-task-3-open-cabinet-drawer)) that showcase how to use most of the features in ManiSkill.
+
 ## Adding Robot(s) and Assets
 
 Loading these objects is done in the [`_load_actors`]() function.
@@ -51,3 +53,33 @@ Shared:
 
 Not shared
 - link children and parents
+
+
+## Example Task 1: Push Cube
+
+## Example Task 2: Pick Single YCB
+
+The goal of this example task is to demonstrate how to make task building with heterogenous object geometries easy via the actor merging API. Building tasks with heteroenous objects allows for easier diverse data collection and generaliable policy training. The complete task code is at [mani_skill2/envs/tasks/pick_single_ycb.py](https://github.com/haosulab/ManiSkill2/tree/main/mani_skill2/envs/tasks/pick_single_ycb.py)
+
+Previously in PushCube, we showed how one can simply create a single object like a cube, and ManiSkill will automatically spawn that cube in every sub-scene. To create a different object in each sub-scene, in this case a random object sampled from the YCB object Dataset, you must do this part yourself. As a user you simply write code to decide which sub-scene will have which object. This is done by creating an actor builder as usual, but now setting a scene mask to decide which sub-scenes have this object and which do not.
+
+```python
+for i, model_id in enumerate(model_ids):
+  builder, obj_height = build_actor_ycb(
+      model_id, self._scene, name=model_id, return_builder=True
+  )
+  scene_mask = np.zeros(self.num_envs, dtype=bool)
+  scene_mask[i] = True
+  builder.set_scene_mask(scene_mask)
+  actors.append(builder.build(name=f"{model_id}-{i}"))
+  self.obj_heights.append(obj_height)
+```
+
+The snippet above will now create a list of `Actor` objects, but this makes fetching data about these different actors complicated because you would have to loop over each one. Here you can now use the merge API shown below to simply merge all of these `Actor` objects in the `actors` list into one object that you can then fetch data shared across all objects like pose, linear velocity etc.
+
+```python
+self.obj = Actor.merge(actors, name="ycb_object")
+```
+
+
+## Example Task 3: Open Cabinet Drawer

docs/source/tutorials/domain_randomization.md

@@ -0,0 +1 @@
+# Domain Randomization

docs/source/tutorials/index.md

@@ -1,14 +1,14 @@
 # Tutorials
 
-These are tutorials written by the maintainers of ManiSkill and the community, spanning topics from how to build your own environment/task, to domain randomization, to reinforcement learning. All the tutorial code can be found [here](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials).
-
+These are tutorials written by the maintainers of ManiSkill and the community, spanning topics from how to build your own environment/task, to domain randomization, to reinforcement learning. The markdown tutorials are linked below with all tutorial code saved in the [examples/tutorials folder ](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials). Some tutorials will also have jupyter notebooks / google colab links that let you run the tutorials without needing your own GPU.
+<!-- 
 - Getting Started: [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/1_quickstart.ipynb), [Colab](https://colab.research.google.com/github/haosulab/ManiSkill2/blob/main/examples/tutorials/1_quickstart.ipynb)
 - Reinforcement Learning: [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/2_reinforcement_learning.ipynb), [Colab](https://colab.research.google.com/github/haosulab/ManiSkill2/blob/main/examples/tutorials/2_reinforcement_learning.ipynb)
 - Imitation Learning: [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/3_imitation_learning.ipynb), [Colab](https://colab.research.google.com/github/haosulab/ManiSkill2/blob/main/examples/tutorials/3_imitation_learning.ipynb)
 - Environment Customization: [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/customize_environments.ipynb), [Colab](https://colab.research.google.com/github/haosulab/ManiSkill2/blob/main/examples/tutorials/customize_environments.ipynb)
-- Advanced Rendering (ray tracing, stereo depth sensor): [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/advanced_rendering.ipynb)
+- Advanced Rendering (ray tracing, stereo depth sensor): [Jupyter Notebook](https://github.com/haosulab/ManiSkill2/blob/main/examples/tutorials/advanced_rendering.ipynb) -->
 
-ManiSkill runs on SAPIEN. SAPIEN tutorials are [here](https://sapien.ucsd.edu/docs/latest/).
+<!-- ManiSkill runs on SAPIEN. SAPIEN tutorials are [here](https://sapien.ucsd.edu/docs/latest/). -->
 
 ```{toctree}
 :titlesonly:

setup.py

@@ -53,7 +53,7 @@
             # Note that currently sphinx 7 does not work, so we must use v6.2.1. See https://github.com/kivy/kivy/issues/8230 which tracks this issue. Once fixed we can use a later version
             "sphinx==6.2.1",
             "sphinx-autobuild",
-            "furo",
+            "sphinx-book-theme",
             # For spelling
             "sphinxcontrib.spelling",
             # Type hints support