Wd/tutorials ci (#833)

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/<TUTORIAL_THEME>`.
+- 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 `<TUTORIAL_THEME>: <TUTORIAL_TOPIC>`.
+- 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!

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}

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(

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(

tutorials/Ray/requirements.txt

@@ -1,3 +1,5 @@
+# not confirmed
+
 pickle5==0.0.11
 Pillow==9.2.0
 torch==1.12.1

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()
 
 

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):