Add supersuit links to documentation and add examples for RescaleObservation and ReshapeObservation (#210)

Author: pseudo-rnd-thoughts

Diff for: docs/api/experimental.md

@@ -22,12 +22,13 @@ The gymnasium ``Env`` provides high flexibility for the implementation of indivi
 
 Gymnasium already contains a large collection of wrappers, but we believe that the wrappers can be improved to
 
- * Support arbitrarily complex observation / action spaces. As RL has advanced, action and observation spaces are becoming more complex and the current wrappers were not implemented with these spaces in mind.
- * Support for numpy, jax and pytorch data. With hardware accelerated environments, i.e. Brax, written in Jax and similar pytorch based programs, numpy is not the only game in town anymore. Therefore, these upgrades will use Jumpy for calling numpy, jax and torch depending on the data.
- * More wrappers. Projects like Supersuit aimed to bring more wrappers for RL however wrappers can be moved into Gymnasium.
- * Versioning. Like environments, the implementation details of wrapper can cause changes agent performance. Therefore, we propose adding version numbers with all wrappers.
+* (Work in progress) Support arbitrarily complex observation / action spaces. As RL has advanced, action and observation spaces are becoming more complex and the current wrappers were not implemented with this mind.
+* Support for Jax-based environments. With hardware accelerated environments, i.e. Brax, written in Jax and similar PyTorch based programs, NumPy is not the only game in town anymore. Therefore, these upgrades will use [Jumpy](https://github.com/farama-Foundation/jumpy), a project developed by Farama Foundation to provide automatic compatibility for NumPy, Jax and in the future PyTorch data for a large subset of the NumPy functions.
+* More wrappers. Projects like [Supersuit](https://github.com/farama-Foundation/supersuit) aimed to bring more wrappers for RL, however, many users were not aware of the wrappers, so we plan to move the wrappers into Gymnasium. If we are missing common wrappers from the list provided above, please create an issue.
+* Versioning. Like environments, the implementation details of wrappers can cause changes in agent performance. Therefore, we propose adding version numbers to all wrappers, i.e., `LambaActionV0`. We don't expect these version numbers to change regularly similar to environment version numbers and should ensure that all users know when significant changes could affect your agent's performance. Additionally, we hope that this will improve reproducibility of RL in the future, this is critical for academia.
+* In v28, we aim to rewrite the VectorEnv to not inherit from Env, as a result new vectorized versions of the wrappers will be provided.
 
- * In v28, we aim to rewrite the VectorEnv to not inherit from Env, as a result new vectorised versions of the wrappers will be provided.
+We aimed to replace the wrappers in gymnasium v0.30.0 with these experimental wrappers.
 
 ### Observation Wrappers
 ```{eval-rst}
@@ -48,11 +49,11 @@ Gymnasium already contains a large collection of wrappers, but we believe that t
       - :class:`experimental.wrappers.GrayscaleObservationV0`
     * - :class:`wrappers.ResizeObservation`
       - :class:`experimental.wrappers.ResizeObservationV0`
-    * - ``supersuit.reshape_v0``
+    * - `supersuit.reshape_v0 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/generic_wrappers/basic_wrappers.py#L40>`_
       - :class:`experimental.wrappers.ReshapeObservationV0`
     * - Not Implemented
       - :class:`experimental.wrappers.RescaleObservationV0`
-    * - ``supersuit.dtype_v0``
+    * - `supersuit.dtype_v0 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/generic_wrappers/basic_wrappers.py#L32>`_
       - :class:`experimental.wrappers.DtypeObservationV0`
     * - :class:`wrappers.PixelObservationWrapper`
       - :class:`experimental.wrappers.PixelObservationV0`
@@ -62,7 +63,7 @@ Gymnasium already contains a large collection of wrappers, but we believe that t
       - :class:`experimental.wrappers.TimeAwareObservationV0`
     * - :class:`wrappers.FrameStack`
       - :class:`experimental.wrappers.FrameStackObservationV0`
-    * - ``supersuit.delay_observations_v0``
+    * - `supersuit.delay_observations_v0 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/generic_wrappers/delay_observations.py#L6>`_
       - :class:`experimental.wrappers.DelayObservationV0`
 ```
 
@@ -75,13 +76,13 @@ Gymnasium already contains a large collection of wrappers, but we believe that t
 
     * - Old name
       - New name
-    * - ``supersuit.action_lambda_v1``
+    * - `supersuit.action_lambda_v1 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/lambda_wrappers/action_lambda.py#L73>`_
       - :class:`experimental.wrappers.LambdaActionV0`
     * - :class:`wrappers.ClipAction`
       - :class:`experimental.wrappers.ClipActionV0`
     * - :class:`wrappers.RescaleAction`
       - :class:`experimental.wrappers.RescaleActionV0`
-    * - ``supersuit.sticky_actions_v0``
+    * - `supersuit.sticky_actions_v0 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/generic_wrappers/sticky_actions.py#L6>`_
       - :class:`experimental.wrappers.StickyActionV0`
 ```
 
@@ -96,7 +97,7 @@ Gymnasium already contains a large collection of wrappers, but we believe that t
       - New name
     * - :class:`wrappers.TransformReward`
       - :class:`experimental.wrappers.LambdaRewardV0`
-    * - ``supersuit.clip_reward_v0``
+    * - `supersuit.clip_reward_v0 <https://github.com/Farama-Foundation/SuperSuit/blob/314831a7d18e7254f455b181694c049908f95155/supersuit/generic_wrappers/basic_wrappers.py#L74>`_
       - :class:`experimental.wrappers.ClipRewardV0`
     * - :class:`wrappers.NormalizeReward`
       - :class:`experimental.wrappers.NormalizeRewardV0`
@@ -136,7 +137,7 @@ Gymnasium already contains a large collection of wrappers, but we believe that t
 
     * - Old name
       - New name
-    * - :class:`wrapper.RecordVideo`
+    * - :class:`wrappers.RecordVideo`
       - :class:`experimental.wrappers.RecordVideoV0`
     * - :class:`wrappers.HumanRendering`
       - :class:`experimental.wrappers.HumanRenderingV0`

Diff for: gymnasium/experimental/wrappers/lambda_observations.py

@@ -250,11 +250,13 @@ def __init__(self, env: gym.Env, keep_dim: bool = False):
 
 
 class ResizeObservationV0(LambdaObservationV0):
-    """Observation wrapper for resize image observations using opencv.
+    """Resizes image observations using OpenCV to shape.
 
     Example:
         >>> import gymnasium as gym
-        >>> env = gym.make("CarRacing-v1")
+        >>> env = gym.make("CarRacing-v2")
+        >>> env.observation_space.shape
+        (96, 96, 3)
         >>> resized_env = ResizeObservationV0(env, (32, 32))
         >>> resized_env.observation_space.shape
         (32, 32, 3)
@@ -293,7 +295,17 @@ def __init__(self, env: gym.Env, shape: tuple[int, ...]):
 
 
 class ReshapeObservationV0(LambdaObservationV0):
-    """Observation wrapper for reshaping the observation."""
+    """Reshapes array based observations to shapes.
+
+    Example:
+        >>> import gymnasium as gym
+        >>> env = gym.make("CarRacing-v1")
+        >>> env.observation_space.shape
+        (96, 96, 3)
+        >>> reshape_env = ReshapeObservationV0(env, (24, 4, 96, 1, 3))
+        >>> reshape_env.observation_space.shape
+        (24, 4, 96, 1, 3)
+    """
 
     def __init__(self, env: gym.Env, shape: int | tuple[int, ...]):
         """Constructor for env with Box observation space that has a shape product equal to the new shape product."""
@@ -315,7 +327,16 @@ def __init__(self, env: gym.Env, shape: int | tuple[int, ...]):
 
 
 class RescaleObservationV0(LambdaObservationV0):
-    """Observation wrapper for rescaling the observations between a minimum and maximum value."""
+    """Linearly rescales observation to between a minimum and maximum value.
+
+    Example:
+        >>> import gymnasium as gym
+        >>> env = gym.make("Pendulum-v1")
+        >>> env.observation_space
+        Box([-1. -1. -8.], [1. 1. 8.], (3,), float32)
+        >>> env = RescaleObservationV0(env, np.array([-2, -1, -10]), np.array([1, 0, 1]))
+        Box([-2. -1. -10.], [1. 0. 1.], (3,), float32)
+    """
 
     def __init__(
         self,