diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 180389d46..42dd229ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,12 +5,13 @@ We welcome: - Bug reports - Pull requests for bug fixes - Documentation improvements +- Tutorials and tutorial improvements We have a bug bounty of sorts for PRs, outlined in the readme If you're thinking about creating submitting a new environment, please contact us first. There's a very small number of things that we'd like to add in the main PettingZoo repo that we haven't already done. -## Contributing +## Contributing to the codebase ### Coding @@ -42,3 +43,24 @@ To use it you first need to have _Make_ installed on your local machine: - Windows: `choco install make` (https://community.chocolatey.org/packages/make) Then `make help` should give all the available commands and you can use `Tab` when writing the command if it's too long to write. For example to run all the tests, one would write `make test-all`. + +## Contributing tutorials +Tutorials are a crucial way to help people learn how to use PettingZoo and we greatly appreciate any contributions. However, we have a few guidelines for tutorials: + +### Tutorial content +- Tutorials should be written in single .py scripts with clear comments explaining the code and thought process with a naive user in mind. +- Tutorials should be within their own directory within `/tutorials/`, with the directory name being the tutorial theme. +- Tutorials should come with their own **fully versioned** `requirements.txt` file that minimally lists all required dependencies needed to run all .py scripts within the directory. +- The `requirements.txt` file should include `pettingzoo`, fixed to the current release (eg. `pettingzoo==1.22.0`). + +### Adding your tutorials to the docs +- Create the directory `/docs/tutorials/`. +- You should make a `.md` file for each tutorial within the above directory. +- Each `.md` file should have an "Environment Setup" section and a "Code" section. The title should be of the format `: `. +- The Environment Setup section should reference the `requirements.txt` file you created using `literalinclude`. +- The Code section should reference the `.py` file you created using `literalinclude`. +- `/docs/index.md` should be modified to include every new tutorial. + +### Testing your tutorial +- Tutorial themes should be added to `.github/workflows/linux-tutorials-test.yml`, by adding the theme name to the `tutorial` part of the `matrix`. +- When making a pull request, tests for the newly added tutorials should run. We cannot accept any tutorials that fail any tests, though we can provide assistance in debugging errors - feel free to reach out for advice at any stage! \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 323f8885b..10a3452a8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,11 +41,6 @@ environments/third_party_envs :caption: Tutorials tutorials/cleanrl/implementing_PPO -tutorials/tianshou/beginner -tutorials/tianshou/intermediate -tutorials/tianshou/advanced -tutorials/rllib/holdem -tutorials/rllib/pistonball ``` ```{toctree} diff --git a/tutorials/Ray/render_rllib_leduc_holdem.py b/tutorials/Ray/render_rllib_leduc_holdem.py index 8c28b8af5..ae09dda73 100644 --- a/tutorials/Ray/render_rllib_leduc_holdem.py +++ b/tutorials/Ray/render_rllib_leduc_holdem.py @@ -18,6 +18,10 @@ from pettingzoo.classic import leduc_holdem_v4 +raise NotImplementedError( + "There are currently bugs in this tutorial, we will fix them soon." +) + os.environ["SDL_VIDEODRIVER"] = "dummy" parser = argparse.ArgumentParser( diff --git a/tutorials/Ray/render_rllib_pistonball.py b/tutorials/Ray/render_rllib_pistonball.py index 896ffaf2a..4add671fd 100644 --- a/tutorials/Ray/render_rllib_pistonball.py +++ b/tutorials/Ray/render_rllib_pistonball.py @@ -19,6 +19,10 @@ from pettingzoo.butterfly import pistonball_v6 from tutorials.Ray.rllib_pistonball import CNNModelV2 +raise NotImplementedError( + "There are currently bugs in this tutorial, we will fix them soon." +) + os.environ["SDL_VIDEODRIVER"] = "dummy" parser = argparse.ArgumentParser( diff --git a/tutorials/Ray/requirements.txt b/tutorials/Ray/requirements.txt index 271a6297f..09852e6ea 100644 --- a/tutorials/Ray/requirements.txt +++ b/tutorials/Ray/requirements.txt @@ -1,3 +1,5 @@ +# not confirmed + pickle5==0.0.11 Pillow==9.2.0 torch==1.12.1 diff --git a/tutorials/Ray/rllib_leduc_holdem.py b/tutorials/Ray/rllib_leduc_holdem.py index 4c80010dd..eeb9f5b41 100644 --- a/tutorials/Ray/rllib_leduc_holdem.py +++ b/tutorials/Ray/rllib_leduc_holdem.py @@ -18,6 +18,10 @@ from pettingzoo.classic import leduc_holdem_v4 +raise NotImplementedError( + "There are currently bugs in this tutorial, we will fix them soon." +) + torch, nn = try_import_torch() diff --git a/tutorials/Ray/rllib_pistonball.py b/tutorials/Ray/rllib_pistonball.py index 6159e89af..173bd1dca 100644 --- a/tutorials/Ray/rllib_pistonball.py +++ b/tutorials/Ray/rllib_pistonball.py @@ -16,6 +16,10 @@ from pettingzoo.butterfly import pistonball_v6 +raise NotImplementedError( + "There are currently bugs in this tutorial, we will fix them soon." +) + class CNNModelV2(TorchModelV2, nn.Module): def __init__(self, obs_space, act_space, num_outputs, *args, **kwargs):