Improve the migration guide (#1412)

docs/conf.py

@@ -124,7 +124,7 @@ sphinx_gallery.gen_rst.EXAMPLE_HEADER = """
 .. rst-class:: sphx-glr-example-title
 
 .. note::
-    This example is compatible with Gymnasium version |release|.
+    This tutorial is compatible with Gymnasium version |release|.
 
 .. _sphx_glr_{1}:
 

docs/index.md

@@ -17,7 +17,7 @@ An API standard for reinforcement learning with a diverse collection of referenc
    :width: 500
 ```
 
-**Gymnasium is a maintained fork of OpenAI’s Gym library.** The Gymnasium interface is simple, pythonic, and capable of representing general RL problems, and has a [compatibility wrapper](introduction/gym_compatibility) for old Gym environments:
+**Gymnasium is a maintained fork of OpenAI’s Gym library.** The Gymnasium interface is simple, pythonic, and capable of representing general RL problems, and has a [migration guide](introduction/migration_guide) for old Gym environments:
 
 ```{code-block} python
 import gymnasium as gym
@@ -51,7 +51,6 @@ introduction/train_agent
 introduction/create_custom_env
 introduction/record_agent
 introduction/speed_up_env
-introduction/gym_compatibility
 introduction/migration_guide
 ```
 

docs/introduction/gym_compatibility.md

@@ -1,52 +0,0 @@
----
-layout: "contents"
-title: Compatibility With Gym
----
-
-# Compatibility with Gym
-
-Gymnasium provides a number of compatibility methods for using older Gym Environment implementations.
-
-## Loading OpenAI Gym environments
-
-```{eval-rst}
-.. py:currentmodule:: gymnasium.wrappers
-
-For environments that are registered solely in OpenAI Gym and not in Gymnasium, Gymnasium v0.26.3 and above allows importing them through either a special environment or a wrapper. The ``"GymV26Environment-v0"`` environment was introduced in Gymnasium v0.26.3, and allows importing of Gym environments through the ``env_name`` argument along with other relevant kwargs environment kwargs. To perform conversion through a wrapper, the environment itself can be passed to the wrapper :class:`EnvCompatibility` through the ``env`` kwarg.
-```
-
-```python
-import gymnasium as gym
-
-env = gym.make("GymV26Environment-v0", env_id="GymEnv-v1")
-```
-
-## Gym v0.21 Environment Compatibility
-
-```{eval-rst}
-.. py:currentmodule:: gymnasium
-
-A number of environments have not updated to the recent Gym changes, in particular since v0.21. This update is significant for the introduction of ``termination`` and ``truncation`` signatures in favour of the previously used ``done``. To allow backward compatibility, Gym and Gymnasium v0.26+ include an ``apply_api_compatibility`` kwarg when calling :meth:`make` that automatically converts a v0.21 API compliant environment to one that is compatible with v0.26+.
-```
-
-```python
-import gym
-
-env = gym.make("OldV21Env-v0", apply_api_compatibility=True)
-```
-
-Additionally, in Gymnasium we provide specialist environments for compatibility that for ``env_id`` will call ``gym.make``.
-```python
-import gymnasium
-
-env = gymnasium.make("GymV21Environment-v0", env_id="CartPole-v1", render_mode="human")
-# or
-env = gymnasium.make("GymV21Environment-v0", env=OldV21Env())
-
-```
-
-## Step API Compatibility
-
-```{eval-rst}
-If environments implement the (old) done step API, Gymnasium provides both functions (:meth:`gymnasium.utils.step_api_compatibility.convert_to_terminated_truncated_step_api`) and wrappers (:class:`gymnasium.wrappers.StepAPICompatibility`) that will convert an environment with the old step API (using ``done``) to the new step API (using ``termination`` and ``truncation``).
-```

docs/introduction/migration_guide.md

@@ -3,7 +3,7 @@ layout: "contents"
 title: Migration Guide
 ---
 
-# Migration Guide - v0.21 to v1.0.0
+# Migration Guide from v0.21+
 
 ## Who Should Read This Guide?
 
@@ -21,6 +21,7 @@ title: Migration Guide
 Gymnasium is a fork of `OpenAI Gym v0.26 <https://github.com/openai/gym/releases/tag/0.26.2>`_, which introduced breaking changes from `Gym v0.21 <https://github.com/openai/gym/releases/tag/v0.21.0>`_. These changes weren't made lightly - they solved important problems that made RL research and development more difficult.
 
 The main issues with the old API were:
+
 - **Ambiguous episode endings**: The single ``done`` flag couldn't distinguish between "task completed" and "time limit reached"
 - **Inconsistent seeding**: Random number generation was unreliable and hard to reproduce
 - **Rendering complexity**: Switching between visual modes was unnecessarily complicated
@@ -95,7 +96,6 @@ env.close()
 Why: Gymnasium is a separate project that maintains and improves upon the original Gym codebase.
 
 ```python
-# Update your imports
 # OLD
 import gym
 
@@ -277,7 +277,6 @@ if terminated:
 ```
 
 This makes time limit detection much cleaner and more explicit.
-```
 
 ## Updating Your Training Code
 
@@ -368,21 +367,33 @@ env = gymnasium.make("ALE/Pong-v5")
 
 ## Compatibility Helpers
 
-### Using Old Environments
+### Loading OpenAI Gym environments
 
-```{eval-rst}
-.. py:currentmodule:: gymnasium
-
-If you need to use an environment that hasn't been updated to the new API:
+For environments that can't be updated to Gymnasium, we provide compatibility wrappers either for v21 and v26 style environments, where either the environment name or the environment itself can be passed.
 
 ```python
-# For environments still using old gym
-env = gym.make("GymV21Environment-v0", env_id="OldEnv-v0")
+import gymnasium
+import shimmy  # install shimmy with `pip install shimmy`
 
-# This wrapper converts old API to new API automatically
+gymnasium.register_envs(shimmy)
+
+
+# Gym v0.21 style environments
+env = gymnasium.make("GymV21Environment-v0", env_id="CartPole-v1")
+# or
+env = gymnasium.make("GymV21Environment-v0", env=OldV21Env())
+
+# Gym v0.26 style environments
+env = gymnasium.make("GymV26Environment-v0", env_id="Cartpole-v1")
+# or
+env = gymnasium.make("GymV26Environment-v0", env=OldV26Env())
 ```
 
-For more details, see the `compatibility guide <gym_compatibility>`_.
+### Step API Compatibility
+
+```{eval-rst}
+If environments implement the (old) done step API, Gymnasium provides functions (:meth:`gymnasium.utils.step_api_compatibility.convert_to_terminated_truncated_step_api` and :meth:`gymnasium.utils.step_api_compatibility.convert_to_done_step_api`) that will convert an environment with the old step API (using ``done``) to the new step API (using ``termination`` and ``truncation``), and vice versa.
+```
 
 ## Testing Your Migration
 
@@ -407,6 +418,6 @@ Use the `from gymnasium.utils.env_checker import check_env` to verify their impl
 4. **Compare old vs new behavior**: Run the same code with both APIs to understand differences
 
 **Common resources**:
-- [Gymnasium documentation](https://gymnasium.farama.org/)
+- [Gymnasium API documentation](https://gymnasium.farama.org/api/env)
 - [GitHub issues](https://github.com/Farama-Foundation/Gymnasium/issues) for bug reports
 - [Discord community](https://discord.gg/bnJ6kubTg6) for questions