Skip to content

Commit

Permalink
[Docs] Upgrading docs (#516)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
StoneT2000 authored Aug 22, 2024
1 parent 3779849 commit ad5bcde
Show file tree
Hide file tree
Showing 32 changed files with 442 additions and 158 deletions.
3 changes: 2 additions & 1 deletion docs/.gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
build
build
source/user_guide/reference/_autosummary/
3 changes: 3 additions & 0 deletions docs/source/_static/css/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.logo__image {
padding: 10px;
}
16 changes: 16 additions & 0 deletions docs/source/_static/favicon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions docs/source/_static/logo_black.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/source/_static/logo_black_notext.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions docs/source/_static/logo_white.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/source/_static/logo_white_notext.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions docs/source/_static/version_switcher.json
Original file line number Diff line number Diff line change
@@ -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
}
]
28 changes: 28 additions & 0 deletions docs/source/_templates/class_no_parameters.rst
Original file line number Diff line number Diff line change
@@ -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 %}
48 changes: 42 additions & 6 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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",
Expand All @@ -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,
Expand All @@ -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)}
2 changes: 1 addition & 1 deletion docs/source/user_guide/datasets/demos.md
Original file line number Diff line number Diff line change
@@ -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. -->
Expand Down
32 changes: 20 additions & 12 deletions docs/source/user_guide/getting_started/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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

Expand Down
6 changes: 2 additions & 4 deletions docs/source/user_guide/reference/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,7 @@ Subpackages:
```{toctree}
:titlesonly:
:maxdepth: 1
mani_skill.envs.sapien_env
:glob:
*
mani_skill.utils.common
mani_skill.utils.sapien_utils
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# `mani_skill.agents.base_agent`

```{eval-rst}
.. automodule:: mani_skill.agents.base_agent
:members:
:show-inheritance:
:undoc-members:
```
Original file line number Diff line number Diff line change
@@ -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:
```
10 changes: 10 additions & 0 deletions docs/source/user_guide/reference/mani_skill.envs.scene.md
Original file line number Diff line number Diff line change
@@ -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:
```
15 changes: 15 additions & 0 deletions docs/source/user_guide/reference/mani_skill.sensors.rst
Original file line number Diff line number Diff line change
@@ -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:
7 changes: 0 additions & 7 deletions docs/source/user_guide/reference/mani_skill.utils.common.md

This file was deleted.

10 changes: 10 additions & 0 deletions docs/source/user_guide/reference/mani_skill.utils.common.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
``mani_skill.utils.common`` module
===================================

.. currentmodule:: mani_skill.utils.common

.. automodule:: mani_skill.utils.common
:members:
:undoc-members:

.. rubric:: Functions
Loading

0 comments on commit ad5bcde

Please sign in to comment.