Update documentation, add PR template, CONTRIBUTING.md (#43)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+# Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+
+Fixes # (issue), Depends on # (pull request)
+
+## Type of change
+
+> Please delete options that are not relevant.
+
+- Bug fix (non-breaking change which fixes an issue)
+- New feature (non-breaking change which adds functionality)
+- Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- This change requires a documentation update
+
+### Screenshots
+
+> Please attach before and after screenshots of the change if applicable.
+> To upload images to a PR -- simply drag and drop or copy paste.
+
+# Checklist:
+
+- [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with `pre-commit run --all-files` (see `CONTRIBUTING.md` instructions to set it up)
+- [ ] I have run `pytest -v` and no errors are present.
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] I solved any possible warnings that `pytest -v` has generated that are related to my code to the best of my knowledge.
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+
+<!--
+You can mark something as done by putting an x character in it
+
+For example,
+- [x] I have done this task
+- [ ] I have not done this task
+-->

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Shimmy Contribution Guidelines
+
+We welcome:
+
+- New compatibility wrappers (see [Incoming Projects](https://github.com/Farama-Foundation/Shimmy#incoming-projects))
+- Bug reports
+- Pull requests for bug fixes
+- Documentation improvements
+
+## Contributing to the codebase
+
+### Coding
+
+Contributing code is done through standard github methods:
+
+1. Fork this repo
+3. Commit your code
+4. Submit a pull request. It will be reviewed by maintainers and they'll give feedback or make requests as applicable
+
+### Considerations
+- Make sure existing tests pass (`pip install -e .[all]` and then run `pytest -v` -- may also need to `apt-get`/`brew` `install swig` and `AutoROM -v`)
+- Make sure your new code is properly tested and fully-covered
+- Any fixes to environments should include fixes to the appropriate documentation
+- Changes to environment functionality should be avoided when reasonable, and when they occur the environment version must be bumped.
+
+### Git hooks
+The CI will run several checks on the new code pushed to the PettingZoo repository. These checks can also be run locally without waiting for the CI by following the steps below:
+1. [install `pre-commit`](https://pre-commit.com/#install),
+2. install the Git hooks by running `pre-commit install`.
+
+Once those two steps are done, the Git hooks will be run automatically at every new commit. The Git hooks can also be run manually with `pre-commit run --all-files`, and if needed they can be skipped (not recommended) with `git commit --no-verify`. **Note:** you may have to run `pre-commit run --all-files` manually a couple of times to make it pass when you commit, as each formatting tool will first format the code and fail the first time but should pass the second time.

docs/contents/atari.md

@@ -1,5 +1,13 @@
 ## Atari Environments
 
+### [Arcade Learning Environment (ALE)](https://github.com/mgbellemare/Arcade-Learning-Environment)
+A collection of 50+ Atari 2600 games powered by the [Stella](https://stella-emu.github.io/) emulator.
+
+```{figure} /_static/img/ALE.png
+    :name: ALE
+    :alt: Arcade Learning Environment
+    :width: 60%
+```
 
 ### Installation
 ```

docs/contents/dm_control.md

@@ -1,16 +1,44 @@
-## dm-control (single agent)
+## DM Control
+### [DeepMind Control](https://github.com/deepmind/dm_control/)
+DM Control is a framework for physics-based simulation and reinforcement learning environments using the [MuJoCo](https://github.com/deepmind/mujoco#) physics engine. 
 
+Shimmy provides compatibility wrappers for the base environments in [Control Suite](https://github.com/deepmind/dm_control/blob/main/dm_control/suite/README.md), as well as custom environments using [Locomotion](https://github.com/deepmind/dm_control/blob/main/dm_control/locomotion/README.md).
+
+```{figure} /_static/img/dm_locomotion.png
+    :name: locomotion
+    :alt: DeepMind Locomotion
+    :width: 80%
+```
 
 ### Installation
 ```
 pip install shimmy[dm-control]
 ```
 
 ### Usage (Single agent)
+To run a `dm_control` environment:
 ```python
 import gymnasium as gym
+env = gym.make("dm_control/acrobot-swingup_sparse-v0", render_mode="human")
+observation, info = env.reset(seed=42)
+for _ in range(1000):
+   action = env.action_space.sample()  # this is where you would insert your policy
+   observation, reward, terminated, truncated, info = env.step(action)
 
-env = gym.make("dm_control/acrobot_swingup_sparse-v0")
+   if terminated or truncated:
+      observation, info = env.reset()
+env.close()
+```
+
+To get a list of all available `dm_control` environments (85 total):
+```python
+from gymnasium.envs.registration import registry
+DM_CONTROL_ENV_IDS = [
+    env_id
+    for env_id in registry
+    if env_id.startswith("dm_control") and env_id != "dm_control/compatibility-env-v0"
+]
+print(DM_CONTROL_ENV_IDS)
 ```
 
 ### Class Description

docs/contents/dm_lab.md

@@ -1,7 +1,25 @@
 ## DM Lab
 
+### [DeepMind Lab](https://github.com/deepmind/lab)
+
+Suite of challenging 3D navigation and puzzle-solving tasks for learning agents, based on id Software's
+[Quake III Arena](https://github.com/id-Software/Quake-III-Arena) via
+[ioquake3](https://github.com/ioquake/ioq3) and
+[other open source software](#upstream-sources).
+
+```{figure} /_static/img/dm_lab.gif
+    :name: DM lab
+    :alt: DeepMind Lab
+    :width: 60%
+```
+
+
 ### Installation
 
+```
+pip install shimmy
+```
+
 Courtesy to [Danijar Hafner](https://github.com/deepmind/lab/issues/242) for providing this install script.
 ```bash
 #!/bin/sh

docs/contents/dm_multi.md

@@ -1,8 +1,17 @@
-## dm-control soccer (multi-agent)
+## DM Control (multi-agent)
+
+### [DeepMind Control: Soccer](https://shimmy.farama.org/contents/dm_multi/)
+Multi-agent robotics environment where teams of agents compete in soccer. It extends the single-agent [DM Control Locomotion](https://github.com/deepmind/dm_control/blob/main/dm_control/locomotion/README.md) library, powered by the [MuJoCo](https://github.com/deepmind/mujoco#) physics engine.
+
+```{figure} /_static/img/dm_soccer.png
+    :name: DM soccer
+    :alt: DeepMind Soccer
+    :width: 60%
+```
 
 ### Installation
 ```
-pip install shimmy[dm-control]
+pip install shimmy[dm-control-multi-agent]
 ```
 
 ### Usage (Multi agent)
@@ -24,6 +33,12 @@ env = dm_soccer.load(
 )
 
 env = DmControlMultiAgentCompatibilityV0(env)
+
+observations = env.reset()
+while env.agents:
+    actions = {agent: env.action_space(agent).sample() for agent in env.agents}  # this is where you would insert your policy
+    observations, rewards, terminations, truncations, infos = env.step(actions)
+env.close()
 ```
 
 ### Class Description

docs/contents/gym.md

@@ -1,5 +1,14 @@
 ## OpenAI Gym
 
+### [OpenAI Gym](https://github.com/openai/gym)
+
+Shimmy provides Gymnasium compatibility wrappers for Gym V26 and V21.
+
+```{figure} /_static/img/openai_gym.png
+    :width: 80%
+    :name: openai gym
+```
+
 ### Installation
 ```
 pip install shimmy[gym]
@@ -9,18 +18,18 @@ pip install shimmy[gym]
 ```python
 import gymnasium as gym
 
-env = gym.make("GymV22CompatibilityV0", env_name="...")
+env = gym.make("GymV21CompatibilityV0", env_name="...")
 ```
 
 ### Class Description
 ```{eval-rst}
 .. autoclass:: shimmy.openai_gym_compatibility.GymV26CompatibilityV0
     :members:
     :undoc-members:
-.. autoclass:: shimmy.openai_gym_compatibility.LegacyV22Env
+.. autoclass:: shimmy.openai_gym_compatibility.LegacyV21Env
     :members:
     :undoc-members:
-.. autoclass:: shimmy.openai_gym_compatibility.GymV22CompatibilityV0
+.. autoclass:: shimmy.openai_gym_compatibility.GymV21CompatibilityV0
     :members:
     :undoc-members:
 .. autofunction:: shimmy.openai_gym_compatibility._strip_default_wrappers

docs/contents/open_spiel.md

@@ -1,8 +1,31 @@
-## OpenSpiel
+## OpenSpiel (multi-agent)
+
+
+### [DeepMind OpenSpiel](https://github.com/deepmind/open_spiel)
+
+OpenSpiel is a collection of 70+ environments for common board games, card games, as well as simple grid worlds and social dilemmas.
+
+It supports n-player (single- and multi- agent) zero-sum, cooperative and general-sum, one-shot and sequential, strictly turn-taking and simultaneous-move, perfect and imperfect information games.
+
+
+[//]: # (Supports:)
+
+[//]: # (* n-player (single- and multi- agent) zero-sum, cooperative and general-sum games.)
+
+[//]: # (* one-shot and sequential, strictly turn-taking and simultaneous-move games.)
+
+[//]: # (* perfect and imperfect information games.)
+
+[//]: # (* traditional multiagent environments such as (partially- and fully- observable) grid worlds and social dilemmas.)
+
+```{figure} /_static/img/openspiel.png
+    :name: open spiel
+```
+
 
 ### Installation
 ```
-pip install shimmy[pettingzoo]
+pip install shimmy[openspiel]
 ```
 
 ### Usage

docs/index.md

@@ -7,7 +7,8 @@ lastpage:
 
 # Shimmy is an API conversion tool for popular external reinforcement learning environments to [Gymnasium](https://github.com/farama-Foundation/gymnasium) and [PettingZoo](https://github.com/farama-Foundation/pettingZoo/) APIs.
 
-```{figure} _static/img/shimmy-white.svg
+```{figure} /_static/img/shimmy-white.svg
+   :name: Shimmy Logo
    :alt: Shimmy Logo
    :width: 200
 ```
@@ -70,7 +71,7 @@ pip install shimmy[gym]
 ```python
 import gymnasium as gym
 
-env = gym.make("GymV22CompatibilityV0", env_name="...")
+env = gym.make("GymV21CompatibilityV0", env_name="...")
 ```
 
 ### Atari Environments