Update docs (#837)

.github/workflows/build-docs.yml

@@ -8,23 +8,26 @@ jobs:
   docs:
     name: Generate Website
     runs-on: ubuntu-latest
-    
+
     steps:
       - uses: actions/checkout@v3
 
       - uses: actions/setup-python@v4
         with:
-            python-version: '3.9' 
+            python-version: '3.9'
 
       - name: Install dependencies
         run: pip install -r docs/requirements.txt
-      
+
       - name: Install PettingZoo
         run: pip install .
-      
+
       - name: Generate environment docs
         run: python docs/_scripts/gen_envs_mds.py
-
+
+      - name: Generate environments display
+        run: python docs/_scripts/gen_envs_display.py
+
       - name: Build
         run: sphinx-build -b dirhtml -v docs _build
 

docs/.gitignore

@@ -1 +1,2 @@
-environments/**/*.md
+environments/**/*.md
+environments/**/list.html

docs/README.md

@@ -0,0 +1,38 @@
+# PettingZoo docs
+
+This folder contains the documentation for [PettingZoo](https://github.com/Farama-Foundation/PettingZoo).
+
+## Instructions for editing content
+
+Our documentation is written in Markdown (more precisely, MyST - Markedly Structured Text) and built using [Sphinx](https://www.sphinx-doc.org/en/master/).
+All content present in the documentation website can be found in this directory except for the environments.
+
+### Editing an environment page
+
+Environemnts' documentation can be found at the top of the file python file where the environment is declared, for example, the documentation for the chess environment can be at [/pettingzoo/classic/chess/chess.py](https://github.com/Farama-Foundation/PettingZoo/blob/master/pettingzoo/classic/chess/chess.py)
+
+To generate the environments pages you need to execute the `_scripts/gen_envs_mds.py` script.
+
+## Build the Documentation
+
+Install the required packages and PettingZoo:
+
+```
+pip install -e .
+cd docs/
+pip install -r requirements.txt
+```
+
+To build the documentation once:
+
+```
+cd docs
+make dirhtml _build
+```
+
+To rebuild the documentation automatically every time a change is made:
+
+```
+cd docs
+sphinx-autobuild -b dirhtml . _build
+```

docs/_scripts/gen_envs_display.py

@@ -1,3 +1,4 @@
+import os
 import sys
 
 all_envs = {
@@ -111,8 +112,8 @@ def generate_page(env_type_id, env_list, limit=-1, base_path=""):
 
     for key in all_envs.keys():
         env_list = all_envs[key]
-        envs_path = f"../environments/{key}"
+        envs_path = os.path.join(os.path.dirname(__file__), "..", "environments", key)
         page = generate_page(key, env_list)
-        fp = open(f"{envs_path}/list.html", "w+", encoding="utf-8")
+        fp = open(os.path.join(envs_path, "list.html"), "w+", encoding="utf-8")
         fp.write(page)
         fp.close()

docs/_scripts/gen_envs_mds.py

@@ -7,7 +7,7 @@
 
 
 def add_frontmatter(text, frontmatter_options):
-    frontmatter_text = "---"
+    frontmatter_text = "---\nautogenerated:"
     for key, value in frontmatter_options.items():
         frontmatter_text += f"\n{key}: {value}"
     frontmatter_text += "\n---\n\n"

docs/conf.py

@@ -20,7 +20,7 @@
 import pettingzoo
 
 project = "PettingZoo"
-copyright = "2022"
+copyright = "2022 Farama Foundation"
 author = "Farama Foundation"
 
 # The full version, including alpha/beta/rc tags