diff --git a/docs/source/conf.py b/docs/source/conf.py index dee09effc..74f75c4b8 100644 --- a/docs/source/conf.py +++ b/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/", -} +} \ No newline at end of file diff --git a/docs/source/tutorials/custom_environments.md b/docs/source/tutorials/custom_environments.md index 728a925f9..f5efd0ecd 100644 --- a/docs/source/tutorials/custom_environments.md +++ b/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 \ No newline at end of file diff --git a/docs/source/tutorials/domain_randomization.md b/docs/source/tutorials/domain_randomization.md new file mode 100644 index 000000000..cdc812989 --- /dev/null +++ b/docs/source/tutorials/domain_randomization.md @@ -0,0 +1 @@ +# Domain Randomization \ No newline at end of file diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md index ff8a1f257..ed84ce564 100644 --- a/docs/source/tutorials/index.md +++ b/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. + -ManiSkill runs on SAPIEN. SAPIEN tutorials are [here](https://sapien.ucsd.edu/docs/latest/). + ```{toctree} :titlesonly: diff --git a/setup.py b/setup.py index a72c1ff91..33f1857b3 100644 --- a/setup.py +++ b/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