Update all the environment docs (#566)

docs/_scripts/gen_environment_page.py

@@ -0,0 +1,77 @@
+import itertools
+
+import ale_py
+import gymnasium
+import tabulate
+from ale_py.registration import _rom_id_to_name
+from tqdm import tqdm
+
+gymnasium.register_envs(ale_py)
+
+impossible_roms = {"maze_craze", "joust", "warlords", "combat"}
+ALL_ATARI_GAMES = {
+    env_spec.kwargs["game"]
+    for env_spec in gymnasium.registry.values()
+    if isinstance(env_spec.entry_point, str)
+    and "ale_py" in env_spec.entry_point
+    and env_spec.kwargs["game"] not in impossible_roms
+}
+
+# Generate the list of all atari games on atari.md
+for rom_id in sorted(ALL_ATARI_GAMES):
+    print(f"atari/{rom_id}")
+
+
+def generate_value_ranges(values):
+    for a, b in itertools.groupby(enumerate(values), lambda pair: pair[1] - pair[0]):
+        b = list(b)
+        yield b[0][1], b[-1][1]
+
+
+def shortened_repr(values):
+    output = []
+    for low, high in generate_value_ranges(values):
+        if high - low < 5:
+            output.append(", ".join(map(str, range(low, high + 1))))
+        else:
+            output.append(f"{low}, ..., {high}")
+    return "[" + ", ".join(output) + "]"
+
+
+# # Generate difficult levels table on atari.md
+headers = [
+    "Environment",
+    "Possible Modes",
+    "Default Mode",
+    "Possible Difficulties",
+    "Default Difficulty",
+]
+rows = []
+
+for rom_id in tqdm(ALL_ATARI_GAMES):
+    env_name = _rom_id_to_name(rom_id)
+
+    env = gymnasium.make(f"ALE/{env_name}-v5").unwrapped
+
+    available_difficulties = env.ale.getAvailableDifficulties()
+    default_difficulty = env.ale.cloneState().getDifficulty()
+    available_modes = env.ale.getAvailableModes()
+    default_mode = env.ale.cloneState().getCurrentMode()
+
+    if env_name == "VideoCube":
+        available_modes = "[0, 1, 2, 100, 101, 102, ..., 5000, 5001, 5002]"
+    else:
+        available_modes = shortened_repr(available_modes)
+
+    rows.append(
+        [
+            env_name,
+            available_modes,
+            default_mode,
+            shortened_repr(available_difficulties),
+            default_difficulty,
+        ]
+    )
+    env.close()
+
+print(tabulate.tabulate(rows, headers=headers, tablefmt="github"))

docs/_scripts/gen_environments_md.py

@@ -18,10 +18,6 @@
     and env_spec.kwargs["game"] not in impossible_roms
 }
 
-# Generate the list of all atari games on atari.md
-for rom_id in sorted(ALL_ATARI_GAMES):
-    print(f"atari/{rom_id}")
-
 
 def generate_value_ranges(values):
     for a, b in itertools.groupby(enumerate(values), lambda pair: pair[1] - pair[0]):
@@ -39,83 +35,40 @@ def shortened_repr(values):
     return "[" + ", ".join(output) + "]"
 
 
-# # Test examples
-# print(shortened_repr([0]))
-# print(shortened_repr([1, 2, 3]))
-# print(shortened_repr([0, 1, 2, 3]))
-# print(shortened_repr([0, 4, 8, 12, 16, 20, 24, 28]))
-# print(shortened_repr(list(range(32)) + [128]))
-
-
-# # Generate difficult levels table on atari.md
-headers = [
-    "Environment",
-    "Possible Modes",
-    "Default Mode",
-    "Possible Difficulties",
-    "Default Difficulty",
-]
-rows = []
-
-for rom_id in tqdm(ALL_ATARI_GAMES):
-    env_name = _rom_id_to_name(rom_id)
-
-    env = gymnasium.make(f"ALE/{env_name}-v5").unwrapped
-
-    available_difficulties = env.ale.getAvailableDifficulties()
-    default_difficulty = env.ale.cloneState().getDifficulty()
-    available_modes = env.ale.getAvailableModes()
-    default_mode = env.ale.cloneState().getCurrentMode()
-
-    if env_name == "VideoCube":
-        available_modes = "[0, 1, 2, 100, 101, 102, ..., 5000, 5001, 5002]"
-    else:
-        available_modes = shortened_repr(available_modes)
-
-    rows.append(
-        [
-            env_name,
-            available_modes,
-            default_mode,
-            shortened_repr(available_difficulties),
-            default_difficulty,
-        ]
-    )
-    env.close()
-
-print(tabulate.tabulate(rows, headers=headers, tablefmt="github"))
-
 # Generate each pages results
-with open("atari-docs.json") as file:
+with open("environment-docs.json") as file:
     atari_data = json.load(file)
 
 for rom_id in tqdm(ALL_ATARI_GAMES):
     env_name = _rom_id_to_name(rom_id)
 
     env = gymnasium.make(f"ALE/{env_name}-v5").unwrapped
-    if rom_id in atari_data:
-        env_data = atari_data[rom_id]
+    env_data = atari_data[rom_id]
 
-        env_description = env_data["env_description"]
-        if env_data["atariage_url"]:
-            env_url = f"""
+    env_description = env_data["env_description"]
+
+    if env_data["atariage_url"]:
+        env_url = f"""
 For a more detailed documentation, see [the AtariAge page]({env_data['atariage_url']})
 """
-        else:
-            env_url = ""
-        reward_description = env_data["reward_description"]
     else:
-        # Add the information to `atari_docs.json` and rerun this file to generate the new documentation
-        env_description = f"{env_name} is missing description documentation. If you are interested in writing up a description, please create an issue or PR with the information on the Gymnasium github."
         env_url = ""
+
+    if env_data["reward_description"]:
+        reward_description = f"""
+### Reward
+
+{env_data["reward_description"]}
+"""
+    else:
         reward_description = ""
 
-    table_values = map(
+    action_table_values = map(
         lambda s: f"`{s}`",
         itertools.chain(*zip(range(env.action_space.n), env.get_action_meanings())),
     )
     default_action_table = tabulate.tabulate(
-        list(itertools.zip_longest(*([iter(table_values)] * 6), fillvalue="")),
+        list(itertools.zip_longest(*([iter(action_table_values)] * 6), fillvalue="")),
         headers=["Value", "Meaning", "Value", "Meaning", "Value", "Meaning"],
         tablefmt="github",
     )
@@ -176,6 +129,16 @@ def shortened_repr(values):
         difficulty_mode_row, headers=difficulty_mode_header, tablefmt="github"
     )
 
+    top_table = tabulate.tabulate(
+        [
+            ["Action Space", str(env.action_space)],
+            ["Observation Space", str(env.observation_space)],
+            ["Import", f'`gymnasium.make("{env.spec.id}")`'],
+        ],
+        headers=["", ""],
+        tablefmt="github",
+    )
+
     env.close()
 
     TEMPLATE = f"""---
@@ -184,18 +147,14 @@ def shortened_repr(values):
 
 # {env_name}
 
-```{{figure}} ../../_static/videos/atari/{rom_id}.gif
+```{{figure}} ../_static/videos/environments/{rom_id}.gif
 :width: 120px
 :name: {env_name}
 ```
 
 This environment is part of the <a href='..'>Atari environments</a>. Please read that page first for general information.
 
-|   |   |
-|---|---|
-| Action Space | {env.action_space} |
-| Observation Space | {env.observation_space} |
-| Import | `gymnasium.make("{env.spec.id}")` |
+{top_table}
 
 For more {env_name} variants with different observation and action spaces, see the variants section.
 
@@ -213,16 +172,14 @@ def shortened_repr(values):
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
-
 {reward_description}
-
 ## Variants
 
 {env_name} has the following variants of the environment id which have the following differences in observation,
@@ -246,5 +203,5 @@ def shortened_repr(values):
 * v4: Stickiness of actions was removed
 * v0: Initial versions release
 """
-    with open(f"../environments/atari/{rom_id}.md", "w") as file:
+    with open(f"../environments/{rom_id}.md", "w") as file:
         file.write(TEMPLATE)

docs/environments/adventure.md

@@ -43,15 +43,14 @@ See [environment specification](../env-spec) to see more information on the acti
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
 
-
 ## Variants
 
 Adventure has the following variants of the environment id which have the following differences in observation,

docs/environments/air_raid.md

@@ -38,15 +38,14 @@ See [environment specification](../env-spec) to see more information on the acti
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
 
-
 ## Variants
 
 AirRaid has the following variants of the environment id which have the following differences in observation,

docs/environments/alien.md

@@ -43,19 +43,17 @@ See [environment specification](../env-spec) to see more information on the acti
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
 
-### Rewards
+### Reward
 
-You score points by destroying eggs, killing aliens, using pulsars, and collecting special prizes. When you are caught
-by an alien, you will lose one of your lives. The number of lives you have depends on the game flavor. For a
-table of scores corresponding to the different achievements, consult [the AtariAge page](https://atariage.com/manual_html_page.php?SoftwareID=815).
+You score points by destroying eggs, killing aliens, using pulsars, and collecting special prizes. When you are caught by an alien, you will lose one of your lives. The number of lives you have depends on the game flavor. For a table of scores corresponding to the different achievements, consult [the AtariAge page](https://atariage.com/manual_html_page.php?SoftwareID=815).
 
 ## Variants
 

docs/environments/amidar.md

@@ -11,11 +11,11 @@ title: Amidar
 
 This environment is part of the <a href='..'>Atari environments</a>. Please read that page first for general information.
 
-|   |   |
-|---|---|
-| Action Space | Discrete(10) |
+|                   |                                   |
+|-------------------|-----------------------------------|
+| Action Space      | Discrete(10)                      |
 | Observation Space | Box(0, 255, (210, 160, 3), uint8) |
-| Import | `gymnasium.make("ALE/Amidar-v5")` |
+| Import            | `gymnasium.make("ALE/Amidar-v5")` |
 
 For more Amidar variants with different observation and action spaces, see the variants section.
 
@@ -42,18 +42,17 @@ See [environment specification](../env-spec) to see more information on the acti
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
 
-### Rewards
+### Reward
 
-You score points by traversing new parts of the grid. Coloring an entire box in the maze or catching chickens gives extra points.
-For a more detailed documentation, see [the AtariAge page](https://atariage.com/manual_html_page.php?SoftwareID=817).
+You score points by traversing new parts of the grid. Coloring an entire box in the maze or catching chickens gives extra points. For a more detailed documentation, see [the AtariAge page](https://atariage.com/manual_html_page.php?SoftwareID=817).
 
 ## Variants
 

docs/environments/assault.md

@@ -11,11 +11,11 @@ title: Assault
 
 This environment is part of the <a href='..'>Atari environments</a>. Please read that page first for general information.
 
-|   |   |
-|---|---|
-| Action Space | Discrete(7) |
-| Observation Space | Box(0, 255, (210, 160, 3), uint8) |
-| Import | `gymnasium.make("ALE/Assault-v5")` |
+|                   |                                    |
+|-------------------|------------------------------------|
+| Action Space      | Discrete(7)                        |
+| Observation Space | Box(0, 255, (210, 160, 3), uint8)  |
+| Import            | `gymnasium.make("ALE/Assault-v5")` |
 
 For more Assault variants with different observation and action spaces, see the variants section.
 
@@ -41,15 +41,14 @@ See [environment specification](../env-spec) to see more information on the acti
 
 ## Observations
 
-Atari environments have three possible observation types: `"rgb"`, `"grayscale"` and `"ram"`.
+Atari environments have three possible observation types:
 
-- `obs_type="rgb" -> observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
-- `obs_type="ram" -> observation_space=Box(0, 255, (128,), np.uint8)`
-- `obs_type="grayscale" -> Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the "rgb" type
+- `obs_type="rgb"` -> `observation_space=Box(0, 255, (210, 160, 3), np.uint8)`
+- `obs_type="ram"` -> `observation_space=Box(0, 255, (128,), np.uint8)`
+- `obs_type="grayscale"` -> `Box(0, 255, (210, 160), np.uint8)`, a grayscale version of the q"rgb" type
 
 See variants section for the type of observation used by each environment id by default.
 
-
 ## Variants
 
 Assault has the following variants of the environment id which have the following differences in observation,