Re-organize file structure (#83)

* re-organize files

* solve hand_env import

* auto generate docs

* move citations to docs

* readme merge shadow touch

* fix pydoc

.pre-commit-config.yaml

@@ -46,7 +46,7 @@ repos:
     rev: 6.1.1
     hooks:
       - id: pydocstyle
-        exclude: ^(tests)|(docs)|(gymnasium_robotics/utils)|(gymnasium_robotics/envs/fetch)|(gymnasium_robotics/envs/hand)|(gymnasium_robotics/envs/maze/)|(gymnasium_robotics/envs/adroit_hand)|(gymnasium_robotics/envs/franka_kitchen)
+        exclude: ^(tests)|(docs)|(gymnasium_robotics/utils)|(gymnasium_robotics/envs/fetch)|(gymnasium_robotics/envs/shadow_dexterous_hand)|(gymnasium_robotics/envs/maze)|(gymnasium_robotics/envs/adroit_hand)|(gymnasium_robotics/envs/franka_kitchen)
         args:
           - --convention=google
           - --add-ignore=D100

README.md

@@ -24,11 +24,9 @@ We support and test for Python 3.7, 3.8, 3.9, 3.10 and 3.11 on Linux and macOS.
 `Gymnasium-Robotics` includes the following groups of environments:
 
 * [Fetch](https://robotics.farama.org/envs/#fetch-environments) - A collection of environments with a 7-DoF robot arm that has to perform manipulation tasks such as Reach, Push, Slide or Pick and Place.
-* [Shadow Dexterous Hand](https://robotics.farama.org/envs/#shadow-dexterous-hand-environments) - A collection of environments with a 24-DoF anthropomorphic robotic hand that has to perform object manipulation tasks with a cube, egg-object, or pen.
-* [Shadow Dexterous Hand with Touch Sensors](https://robotics.farama.org/envs/#hand-environments-with-touch-sensors) - Variations of the `Shadow Dexterous Hand` environments that include data from 92 touch sensors in the observation space.
+* [Shadow Dexterous Hand](https://robotics.farama.org/envs/#shadow-dexterous-hand-environments) - A collection of environments with a 24-DoF anthropomorphic robotic hand that has to perform object manipulation tasks with a cube, egg-object, or pen. There are variations of these environments that also include data from 92 touch sensors in the observation space.
 
-The [D4RL](https://github.com/Farama-Foundation/D4RL) environments are now available. These environments have been refactored and may not have the
-same action/observation spaces as the original, please read their documentation:
+The [D4RL](https://github.com/Farama-Foundation/D4RL) environments are now available. These environments have been refactored and may not have the same action/observation spaces as the original, please read their documentation:
 
 * [Maze Environments]() - An agent has to navigate through a maze to reach certain goal position. Two different agents can be used: a 2-DoF force-controlled ball, or the classic `Ant` agent from the [Gymnasium MuJoCo environments](https://gymnasium.farama.org/environments/mujoco/ant/). The environment can be initialized with a variety of maze shapes with increasing levels of difficulty.
 * [Adroit Arm]() - A collection of environments that use the Shadow Dexterous Hand with additional degrees of freedom for the arm movement.
@@ -70,30 +68,4 @@ substitute_terminated = env.compute_terminated(obs["achieved_goal"], substitute_
 substitute_truncated = env.compute_truncated(obs["achieved_goal"], substitute_goal, info)
 ```
 
-The `GoalEnv` class can also be used for custom environments.
-
-## Citation
-
-If using the `Fetch` or `Shadow Hand` environments, please cite:
-
-```bibtex
-@misc{1802.09464,
-  Author = {Matthias Plappert and Marcin Andrychowicz and Alex Ray and Bob McGrew and Bowen Baker and Glenn Powell and Jonas Schneider and Josh Tobin and Maciek Chociej and Peter Welinder and Vikash Kumar and Wojciech Zaremba},
-  Title = {Multi-Goal Reinforcement Learning: Challenging Robotics Environments and Request for Research},
-  Year = {2018},
-  Eprint = {arXiv:1802.09464},
-}
-```
-
-To cite the `Shadow Dexterous Hand with Touch Sensors` environments, please use:
-
-```bibtex
-@article{melnik2021using,
-  title={Using tactile sensing to improve the sample efficiency and performance of deep deterministic policy gradients for simulated in-hand manipulation tasks},
-  author={Melnik, Andrew and Lach, Luca and Plappert, Matthias and Korthals, Timo and Haschke, Robert and Ritter, Helge},
-  journal={Frontiers in Robotics and AI},
-  pages={57},
-  year={2021},
-  publisher={Frontiers}
-}
-```
+The `GoalEnv` class can also be used for custom environments.

docs/envs/fetch/index.md

@@ -16,6 +16,19 @@ The Fetch environments are based on the 7-DoF [Fetch Mobile Manipulator](https:/
     :file: list.html
 ```
 
+## Reference
+
+If using the `Fetch`, please cite:
+
+```bibtex
+@misc{1802.09464,
+  Author = {Matthias Plappert and Marcin Andrychowicz and Alex Ray and Bob McGrew and Bowen Baker and Glenn Powell and Jonas Schneider and Josh Tobin and Maciek Chociej and Peter Welinder and Vikash Kumar and Wojciech Zaremba},
+  Title = {Multi-Goal Reinforcement Learning: Challenging Robotics Environments and Request for Research},
+  Year = {2018},
+  Eprint = {arXiv:1802.09464},
+}
+```
+
 ```{toctree}
 :glob:
 :hidden:

docs/envs/shadow_dexterous_hand/index.md

@@ -0,0 +1,63 @@
+---
+firstpage:
+lastpage:
+---
+
+# Shadow Dexterous Hand
+
+These environments are based on the [Shadow Dexterous Hand](https://www.shadowrobot.com/), 5 which is an anthropomorphic robotic hand with 24 degrees of freedom. Of those 24 joints, 20 can be controlled independently whereas the remaining ones are coupled joints.
+
+* `HandReach-v1`: ShadowHand has to reach with its thumb and a selected finger until they meet at a desired goal position above the palm.
+* `HandManipulateBlock-v1`: ShadowHand has to manipulate a block until it achieves a desired goal position and rotation.
+* `HandManipulateEgg-v1`: ShadowHand has to manipulate an egg until it achieves a desired goal position and rotation.
+* `HandManipulatePen-v1`: ShadowHand has to manipulate a pen until it achieves a desired goal position and rotation.
+
+## Shadow Dexterous Hand with Touch Sensors
+
+Touch sensor observations are also available in all Hand environments, with exception of `HandReach`. These environments add to the palm of the hand and the phalanges of the fingers 92 touch sensors with different recorded data depending on the environment. These touch sensors are:
+- **Boolean Touch Sensor**: the observations of each touch sensor return a value of `0` if no contact is detected with and object, and `1` otherwise.
+- **Continuous Touch Sensor**: the value returned by each touch sensor is a continuous value that represents the external force made by an object over the sensor.
+
+These environments are instanceated by adding the following strings to the Hand environment id's: `_BooleanTouchSensor` or `_ContinuousTouchSensor`. For example, to add boolean touch sensors to `HandManipulateEgg-v1`, make the environment in the following way:
+
+```python
+import gymnasium as gym
+
+env = gym.make('HandManipulateEgg_BooleanTouchSensors-v1')
+```
+
+```{raw} html
+    :file: list.html
+```
+
+## References
+
+If using the `Shadow Hand` environments, please cite:
+
+```bibtex
+@misc{1802.09464,
+  Author = {Matthias Plappert and Marcin Andrychowicz and Alex Ray and Bob McGrew and Bowen Baker and Glenn Powell and Jonas Schneider and Josh Tobin and Maciek Chociej and Peter Welinder and Vikash Kumar and Wojciech Zaremba},
+  Title = {Multi-Goal Reinforcement Learning: Challenging Robotics Environments and Request for Research},
+  Year = {2018},
+  Eprint = {arXiv:1802.09464},
+}
+```
+
+To cite the `Shadow Dexterous Hand with Touch Sensors` environments, please use:
+
+```bibtex
+@article{melnik2021using,
+  title={Using tactile sensing to improve the sample efficiency and performance of deep deterministic policy gradients for simulated in-hand manipulation tasks},
+  author={Melnik, Andrew and Lach, Luca and Plappert, Matthias and Korthals, Timo and Haschke, Robert and Ritter, Helge},
+  journal={Frontiers in Robotics and AI},
+  pages={57},
+  year={2021},
+  publisher={Frontiers}
+}
+```
+
+```{toctree}
+:glob:
+:hidden:
+./*
+```

docs/scripts/gen_envs_display.py

@@ -3,105 +3,18 @@
 import gymnasium as gym
 from tqdm import tqdm
 
-
-def create_grid_cell(type_id, env_id, base_path):
-    return f"""
-            <a href="{base_path}{env_id}">
-                <div class="env-grid__cell">
-                    <div class="cell__image-container">
-                        <img src="/_static/videos/{type_id}/{env_id}.gif">
-                    </div>
-                    <div class="cell__title">
-                        <span>{' '.join(env_id.split('_')).title()}</span>
-                    </div>
-                </div>
-            </a>
-    """
-
-
-def generate_page(env, limit=-1, base_path=""):
-    env_type_id = env["id"]
-    env_list = env["list"]
-    cells = [create_grid_cell(env_type_id, env_id, base_path) for env_id in env_list]
-    non_limited_page = limit == -1 or limit >= len(cells)
-    if non_limited_page:
-        cells = "\n".join(cells)
-    else:
-        cells = "\n".join(cells[:limit])
-
-    more_btn = (
-        """
-<a href="./complete_list">
-    <button class="more-btn">
-        See More Environments
-    </button>
-</a>
-"""
-        if not non_limited_page
-        else ""
-    )
-    return f"""
-<div class="env-grid">
-    {cells}
-</div>
-{more_btn}
-    """
-
-
 if __name__ == "__main__":
     """
     python gen_envs_display
     """
-    # TODO: find a standard way to fetch automatically the environments
-    type_dict = [
-        {
-            "id": "fetch",
-            "list": [
-                "FetchPickAndPlace",
-                "FetchPush",
-                "FetchReach",
-                "FetchSlide",
-            ],
-        },
-        {
-            "id": "hand",
-            "list": [
-                "HandBlock",
-                "HandEgg",
-                "HandPen",
-                "HandReach",
-            ],
-        },
-        {
-            "id": "hand_touch",
-            "list": [
-                "HandBlockTouchSensors",
-                "HandEggTouchSensors",
-                "HandPenTouchSensors",
-            ],
-        },
-    ]
-
-    for type_dict in type_dict:
-        page = generate_page(type_dict)
-        fp = open(
-            os.path.join(
-                os.path.dirname(__file__), "..", "envs", type_dict["id"], "list.html"
-            ),
-            "w",
-            encoding="utf-8",
-        )
-        fp.write(page)
-        fp.close()
-
     # REWRITE: for new environments that don't include Fetch and Shadow Hand (D4RL)
     # TODO: use same format for Fetch and Shadow Hand
     # The environment entrypoints have the following standard: `gymnasium_robotics.envs.env_type.env_name:EnvName`
     all_envs = [
         env_spec.entry_point
         for env_spec in gym.registry.values()
         if env_spec.entry_point.startswith("gymnasium_robotics.envs")
-        and "Mujoco"
+        and "MujocoPy"
         not in env_spec.entry_point  # Exclude Fetch and Shadow Hand environments
     ]
     filtered_envs_by_type = {}