Update docs (#258)

.github/workflows/gh-pages.yml

@@ -18,8 +18,11 @@ jobs:
       - name: Install dependencies
         run: pip install -r docs/requirements.txt && git clone https://github.com/Farama-Foundation/MiniGrid.git && pip install ./MiniGrid
 
+      - name: Register Envs
+        run: cd MiniGrid && pip install -e .
+
       - name: Build Envs Docs
-        run: python docs/scripts/gen_mds.py
+        run: python docs/scripts/gen_mds.py && python docs/scripts/gen_index.py
 
       - name: Build
         run: sphinx-build -b dirhtml -v docs _build

.gitignore

@@ -14,4 +14,7 @@ _build/*
 _site
 .jekyll-cache
 __pycache__
-.vscode/
+.vscode/
+/docs/environments/*.md
+/docs/content/*.md
+/docs/api/*.md

README.md

@@ -28,6 +28,7 @@ Please use this bibtex if you want to cite this repository in your publications:
   howpublished = {\url{https://github.com/Farama-Foundation/MiniGrid}},
 }
 ```
+<br>
 
 List of publications & submissions using Minigrid or BabyAI (please open a pull request to add missing entries):
 - [History Compression via Language Models in Reinforcement Learning.](https://proceedings.mlr.press/v162/paischer22a.html) (Johannes Kepler University Linz, PMLR 2022)
@@ -72,6 +73,7 @@ List of publications & submissions using Minigrid or BabyAI (please open a pull
 - [BabyAI: First Steps Towards Grounded Language Learning With a Human In the Loop](https://arxiv.org/abs/1810.08272) (Mila, ICLR, Oct 2018)
 
 This environment has been built as part of work done at [Mila](https://mila.quebec). The Dynamic obstacles environment has been added as part of work done at [IAS in TU Darmstadt](https://www.ias.informatik.tu-darmstadt.de/) and the University of Genoa for mobile robot navigation with dynamic obstacles.
+<br>
 
 ## Installation
 
@@ -88,6 +90,7 @@ git clone https://github.com/Farama-Foundation/MiniGrid
 cd MiniGrid
 pip install -e .
 ```
+<br>
 
 ## Basic Usage
 
@@ -114,6 +117,7 @@ A sample training command is:
 cd torch-rl
 python3 -m scripts.train --env MiniGrid-Empty-8x8-v0 --algo ppo
 ```
+<br>
 
 ## Wrappers
 
@@ -143,6 +147,7 @@ env = RGBImgPartialObsWrapper(env) # Get pixel observations
 env = ImgObsWrapper(env) # Get rid of the 'mission' field
 obs, _ = env.reset() # This now produces an RGB tensor only
 ```
+<br>
 
 ## Design
 
@@ -177,6 +182,7 @@ You can define your own reward function by creating a class derived
 from `MiniGridEnv`. Extending the environment with new object types or new actions
 should be very easy. If you wish to do this, you should take a look at the
 [minigrid/minigrid.py](minigrid/minigrid.py) source file.
+<br>
 
 ## Included Environments
 
@@ -184,6 +190,7 @@ The environments listed below are implemented in the [minigrid/envs](/minigrid/e
 Each environment provides one or more configurations registered with OpenAI gym. Each environment
 is also programmatically tunable in terms of size/complexity, which is useful for curriculum learning
 or to fine-tune difficulty.
+<br>
 
 ### Empty environment
 

docs/api/wrappers.md

@@ -1,33 +0,0 @@
----
-title: Wrappers
-lastpage:
----
-
-# Wrappers
-
-MiniGrid is built to support tasks involving natural language and sparse rewards.
-The observations are dictionaries, with an 'image' field, partially observable
-view of the environment, a 'mission' field which is a textual string
-describing the objective the agent should reach to get a reward, and a 'direction'
-field which can be used as an optional compass. Using dictionaries makes it
-easy for you to add additional information to observations
-if you need to, without having to encode everything into a single tensor.
-
-There are a variety of wrappers to change the observation format available in [minigrid/wrappers.py](../../../../minigrid/wrappers.py). 
-If your RL code expects one single tensor for observations, take a look at `FlatObsWrapper`. 
-There is also an `ImgObsWrapper` that gets rid of the 'mission' field in observations, leaving only the image field tensor.
-
-Please note that the default observation format is a partially observable view of the environment using a
-compact and efficient encoding, with 3 input values per visible grid cell, 7x7x3 values total.
-These values are **not pixels**. If you want to obtain an array of RGB pixels as observations instead,
-use the `RGBImgPartialObsWrapper`. You can use it as follows:
-
-```python
-import gym
-from minigrid.wrappers import RGBImgPartialObsWrapper, ImgObsWrapper
-
-env = gym.make('MiniGrid-Empty-8x8-v0')
-env = RGBImgPartialObsWrapper(env) # Get pixel observations
-env = ImgObsWrapper(env) # Get rid of the 'mission' field
-obs, _ = env.reset() # This now produces an RGB tensor only
-```

docs/content/basic_usage.md

@@ -4,21 +4,21 @@ title: Basic Usage
 firstpage:
 ---
 
-# Basic Usage
 
 ## Basic Usage
 
 There is a UI application which allows you to manually control the agent with the arrow keys:
+
 ```
 ./minigrid/manual_control.py
 ```
 
 The environment being run can be selected with the `--env` option, eg:
+
 ```
 ./minigrid/manual_control.py --env MiniGrid-Empty-8x8-v0
 ```
 
-
 ## Reinforcement Learning
 
 If you want to train an agent with reinforcement learning, I recommend using the code found in the [torch-rl](https://github.com/lcswillems/torch-rl) repository. 
@@ -26,7 +26,8 @@ This code has been tested and is known to work with this environment. The defaul
 
 A sample training command is:
 
-``` {code-block} python
+```
 cd torch-rl
 python3 -m scripts.train --env MiniGrid-Empty-8x8-v0 --algo ppo
 ```
+

docs/content/installation.md

@@ -1,21 +0,0 @@
----
-layout: "contents"
-title: Installation
-firstpage:
----
-
-# Installation
-
-There is now a [pip package](https://pypi.org/project/minigrid/) available, which is updated periodically:
-
-```
-pip install gym-minigrid
-```
-
-Alternatively, to get the latest version of MiniGrid, you can clone this repository and install the dependencies with `pip3`:
-
-```
-git clone https://github.com/Farama-Foundation/MiniGrid
-cd MiniGrid
-pip install -e .
-```

docs/content/pubs.md

@@ -3,9 +3,10 @@ layout: "contents"
 title: Publications
 firstpage:
 ---
+#List of Publications
 
-# List of publications
-## List of publications & submissions using MiniGrid or BabyAI (please open a pull request to add missing entries):
+
+List of publications & submissions using Minigrid or BabyAI (please open a pull request to add missing entries):
 - [History Compression via Language Models in Reinforcement Learning.](https://proceedings.mlr.press/v162/paischer22a.html) (Johannes Kepler University Linz, PMLR 2022)
 - [Leveraging Approximate Symbolic Models for Reinforcement Learning via Skill Diversity](https://arxiv.org/abs/2202.02886) (Arizona State University, ICML 2022)
 - [How to Stay Curious while avoiding Noisy TVs using Aleatoric Uncertainty Estimation](https://proceedings.mlr.press/v162/mavor-parker22a.html) (University College London, Boston University, ICML 2022)
@@ -47,4 +48,5 @@ firstpage:
 - [Creating safer reward functions for reinforcement learning agents in the gridworld](https://gupea.ub.gu.se/bitstream/2077/62445/1/gupea_2077_62445_1.pdf) (University of Gothenburg, 2018)
 - [BabyAI: First Steps Towards Grounded Language Learning With a Human In the Loop](https://arxiv.org/abs/1810.08272) (Mila, ICLR, Oct 2018)
 
-This environment has been built as part of work done at [Mila](https://mila.quebec). The Dynamic obstacles environment has been added as part of work done at [IAS in TU Darmstadt](https://www.ias.informatik.tu-darmstadt.de/) and the University of Genoa for mobile robot navigation with dynamic obstacles.
+This environment has been built as part of work done at [Mila](https://mila.quebec). The Dynamic obstacles environment has been added as part of work done at [IAS in TU Darmstadt](https://www.ias.informatik.tu-darmstadt.de/) and the University of Genoa for mobile robot navigation with dynamic obstacles.
+

docs/environments/index.md

@@ -1,37 +0,0 @@
----
-firstpage:
-lastpage:
----
-
-# Included environments
-
-The environments listed below are implemented in the [minigrid/envs](../../../../minigrid/envs) directory.
-Each environment provides one or more configurations registered with OpenAI gym. Each environment
-is also programmatically tunable in terms of size/complexity, which is useful for curriculum learning
-or to fine-tune difficulty.
-
-```{toctree}
-:hidden:
-empty
-four_rooms
-door_key
-multi_room
-fetch
-go_to_door
-put_near
-red_blue_doors
-memory_s7
-locked_room
-key_corridor_s6_r3
-unlock
-unlock_pickup
-blocked_unlock_pickup
-obstructed_maze
-dist_shift2
-lava_gap_s7
-simple_crossing_s11_n5
-dynamic
-go_to_object
-playground
-
-```

docs/index.md

@@ -6,11 +6,10 @@ lastpage:
 
 # MiniGrid is a simple and easily configurable grid world environments for reinforcement learning
 
-
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) 
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-There are other gridworld Gym environments out there, but this one is
+There are other gridworld Gymnasium environments out there, but this one is
 designed to be particularly simple, lightweight and fast. The code has very few
 dependencies, making it less likely to break or fail to install. It loads no
 external sprites/textures, and it can run at up to 5000 FPS on a Core i7
@@ -18,10 +17,11 @@ laptop, which means you can run your experiments faster. A known-working RL
 implementation can be found [in this repository](https://github.com/lcswillems/torch-rl).
 
 Requirements:
-- Python 3.7 to 3.10
-- OpenAI Gym v0.26
-- NumPy 1.18+
-- Matplotlib (optional, only needed for display) - 3.0+
+
+-   Python 3.7 to 3.10
+-   OpenAI Gym v0.26
+-   NumPy 1.18+
+-   Matplotlib (optional, only needed for display) - 3.0+
 
 Please use this bibtex if you want to cite this repository in your publications:
 
@@ -36,6 +36,23 @@ Please use this bibtex if you want to cite this repository in your publications:
 }
 ```
 
+
+## Installation
+
+There is now a [pip package](https://pypi.org/project/minigrid/) available, which is updated periodically:
+
+```
+pip install minigrid
+```
+
+Alternatively, to get the latest version of MiniGrid, you can clone this repository and install the dependencies with `pip3`:
+
+```
+git clone https://github.com/Farama-Foundation/MiniGrid
+cd MiniGrid
+pip install -e .
+```
+
 ```{toctree}
 :hidden:
 :caption: Introduction
@@ -46,7 +63,6 @@ api/wrappers
 content/pubs
 ```
 
-
 ```{toctree}
 :hidden:
 :caption: Environments
@@ -63,3 +79,4 @@ Github <https://github.com/Farama-Foundation/MiniGrid>
 Donate <https://farama.org/donations>
 Contribute to the Docs <https://github.com/Farama-Foundation/MiniGrid/blob/master/.github/PULL_REQUEST_TEMPLATE.md>
 ```
+

docs/scripts/gen_index.py

@@ -0,0 +1,83 @@
+__author__ = "Feng Gu"
+__email__ = "contact@fenggu.me"
+
+"""
+   isort:skip_file
+"""
+
+import os
+
+readme_path = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+    "README.md",
+)
+
+output_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "index.md",
+)
+
+sections = []
+all_text = """---
+hide-toc: true
+firstpage:
+lastpage:
+---\n"""
+
+index_toctree = """
+```{toctree}
+:hidden:
+:caption: Introduction
+
+content/installation
+content/basic_usage
+content/pubs
+```
+
+```{toctree}
+:hidden:
+:caption: Wrappers
+
+api/wrappers
+```
+
+
+```{toctree}
+:hidden:
+:caption: Environments
+
+environments/design
+environments/index
+```
+
+```{toctree}
+:hidden:
+:caption: Development
+
+Github <https://github.com/Farama-Foundation/MiniGrid>
+Donate <https://farama.org/donations>
+Contribute to the Docs <https://github.com/Farama-Foundation/MiniGrid/blob/master/.github/PULL_REQUEST_TEMPLATE.md>
+```
+
+"""
+# gen index.md
+with open(readme_path) as f:
+    readme = f.read()
+
+    """
+    sections = [description, publications, installation, basic usage, wrappers, design, included environments&etc]
+    """
+    sections = readme.split("<br>")
+    all_text += sections[0]
+    all_text += sections[2]
+all_text += index_toctree
+
+with open(output_path, "w") as f:
+    f.write(all_text)
+
+
+"""
+1. gen index.md
+2. gen /environments/index.md
+3. gen /environments/design.md
+"""

docs/scripts/gen_mds.py

@@ -1,3 +1,5 @@
+import minigrid.wrappers
+
 __author__ = "Feng Gu"
 __email__ = "contact@fenggu.me"
 
@@ -5,14 +7,19 @@ __email__ = "contact@fenggu.me"
    isort:skip_file
 """
 
+import inspect
 import os
 import re
 
 from gymnasium.envs.registration import registry
 from tqdm import tqdm
-
 from utils import trim
 
+readme_path = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+    "README.md",
+)
+
 LAYOUT = "env"
 
 pattern = re.compile(r"(?<!^)(?=[A-Z])")
@@ -20,6 +27,7 @@ pattern = re.compile(r"(?<!^)(?=[A-Z])")
 all_envs = list(registry.values())
 
 filtered_envs_by_type = {}
+env_names = []
 
 # Obtain filtered list
 for env_spec in tqdm(all_envs):
@@ -33,10 +41,9 @@ for env_spec in tqdm(all_envs):
     env_name = split[1]
     filtered_envs_by_type[env_name] = env_spec
 
-
 filtered_envs = {
-    k.split(":")[1]: v
-    for k, v in sorted(
+    env[0]: env[1]
+    for env in sorted(
         filtered_envs_by_type.items(),
         key=lambda item: item[1].entry_point.split(".")[1],
     )
@@ -48,7 +55,12 @@ for env_name, env_spec in filtered_envs.items():
     docstring = trim(made.unwrapped.__doc__)
 
     pascal_env_name = env_spec.id.split("-")[1]
-    snake_env_name = pattern.sub("_", pascal_env_name).lower()
+    # remove suffix
+    p = re.compile(r"([A-Z][a-z]+)*")
+    name = p.search(pascal_env_name).group()
+
+    snake_env_name = pattern.sub("_", name).lower()
+    env_names.append(snake_env_name)
     title_env_name = snake_env_name.replace("_", " ").title()
 
     v_path = os.path.join(
@@ -75,3 +87,136 @@ title: {title_env_name}
     file = open(v_path, "w+", encoding="utf-8")
     file.write(all_text)
     file.close()
+
+
+# gen /environments/index.md
+index_texts = """---
+firstpage:
+lastpage:
+---
+
+"""
+env_index_toctree = """
+```{toctree}
+:hidden:
+"""
+sections = []
+
+with open(readme_path) as f:
+    readme = f.read()
+
+    """
+    sections = [description, publications, installation, basic usage, wrappers, design, included environments&etc]
+    """
+    sections = readme.split("<br>")
+    index_texts += sections[6]
+    index_texts += env_index_toctree
+
+    for env_name in env_names:
+        index_texts += env_name + "\n"
+
+    index_texts += """\n```\n"""
+    f.close()
+
+output_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "environments",
+    "index.md",
+)
+
+# output index.md
+with open(output_path, "w+") as f:
+    f.write(index_texts)
+    f.close()
+
+# gen /environments/design.md
+design_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "environments",
+    "design.md",
+)
+
+design_texts = """---
+layout: "contents"
+title: Design
+firstpage:
+---\n"""
+
+design_texts += sections[5]
+
+with open(design_path, "w+") as f:
+    f.write(design_texts)
+    f.close()
+
+
+# gen /environments/wrappers.md
+
+wrappers_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "api",
+    "wrappers.md",
+)
+
+wrappers_texts = (
+    """---
+title: Wrappers
+lastpage:
+---\n"""
+    + sections[4]
+    + "\n"
+)
+
+for name, obj in inspect.getmembers(minigrid.wrappers):
+    if inspect.isclass(obj) and obj.__doc__ is not None:
+        formatted_doc = " ".join(trim(obj.__doc__).split())
+        wrappers_texts += f"""## {name}
+{formatted_doc}\n\n"""
+
+with open(wrappers_path, "w+") as f:
+    f.write(wrappers_texts)
+    f.close()
+
+
+# gen content/pubs.md
+
+pubs_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "content",
+    "pubs.md",
+)
+
+pubs_texts = (
+    """---
+layout: "contents"
+title: Publications
+firstpage:
+---\n#List of Publications\n"""
+    + sections[1]
+    + "\n"
+)
+
+with open(pubs_path, "w+") as f:
+    f.write(pubs_texts)
+    f.close()
+
+# gen content/basic_usage.md
+
+pubs_path = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "content",
+    "basic_usage.md",
+)
+
+pubs_texts = (
+    """---
+layout: "contents"
+title: Basic Usage
+firstpage:
+---\n"""
+    + sections[3]
+    + "\n"
+)
+
+with open(pubs_path, "w+") as f:
+    f.write(pubs_texts)
+    f.close()