Add docs website

.github/workflows/build-docs.yml

@@ -0,0 +1,46 @@
+name: Build Documentation website
+on:
+  push:
+    branches: [master]
+permissions:
+  contents: write
+jobs:
+  docs:
+    name: Generate Website
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+            python-version: '3.9'
+
+      - name: Install freeglut
+        run: sudo apt-get install -y freeglut3-dev xvfb
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Install Miniworld
+        run: pip install .
+
+      - name: Generate Environments page
+        run: xvfb-run -a -s "-screen 0 1024x768x24 -ac +extension GLX +render -noreset" python docs/_scripts/gen_docs_page.py
+
+      - name: Build
+        run: sphinx-build -b dirhtml -v docs _build
+
+      - name: Move 404
+        run: mv _build/404/index.html _build/404.html
+
+      - name: Update 404 links
+        run: python docs/_scripts/move_404.py _build/404.html
+
+      - name: Remove .doctrees
+        run: rm -r _build/.doctrees
+
+      - name: Upload to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: _build

.pre-commit-config.yaml

@@ -8,8 +8,9 @@ repos:
     rev: v2.1.0
     hooks:
       - id: codespell
-#        args:
-#          - --ignore-words-list=
+        args:
+          - --skip=*.svg
+          # - --ignore-words-list=
   - repo: https://github.com/PyCQA/flake8
     rev: 4.0.1
     hooks:

docs/.gitignore

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

docs/404.md

@@ -0,0 +1,3 @@
+# 404 - Page Not Found
+
+## The requested page could not be found.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

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_docs_page.py

@@ -0,0 +1,81 @@
+import os
+import re
+
+import gymnasium as gym
+
+import gym_miniworld
+
+
+# From python docs
+def trim(docstring):
+    if not docstring:
+        return ""
+    # Convert tabs to spaces (following the normal Python rules)
+    # and split into a list of lines:
+    lines = docstring.expandtabs().splitlines()
+    # Determine minimum indentation (first line doesn't count):
+    indent = 232323
+    for line in lines[1:]:
+        stripped = line.lstrip()
+        if stripped:
+            indent = min(indent, len(line) - len(stripped))
+    # Remove indentation (first line is special):
+    trimmed = [lines[0].strip()]
+    if indent < 232323:
+        for line in lines[1:]:
+            trimmed.append(line[indent:].rstrip())
+    # Strip off trailing and leading blank lines:
+    while trimmed and not trimmed[-1]:
+        trimmed.pop()
+    while trimmed and not trimmed[0]:
+        trimmed.pop(0)
+    # Return a single string:
+    return "\n".join(trimmed)
+
+
+LAYOUT = "env"
+
+pattern = re.compile(r"(?<!^)(?=[A-Z])")
+
+miniworld_env_ids = sorted(list(gym_miniworld.envs.env_ids))
+
+previous_env_name = None
+
+for env_id in miniworld_env_ids:
+    res_env_md = "---\nautogenerated:\n---"
+    print(env_id)
+    env_spec = gym.spec(env_id)
+
+    split = env_spec.entry_point.split(":")
+    mod = __import__(split[0], fromlist=[split[1]])
+    env_class = getattr(mod, split[1])
+    docstring = trim(env_class.__doc__)
+
+    # MiniWorld-Hallway -> Hallway
+    env_name = env_spec.name.split("-")[1]
+
+    # We are not adding sub envs like YMazeLeft
+    if previous_env_name is None or previous_env_name not in env_name:
+        previous_env_name = env_name
+        env_name_snake_case = "_".join(env_id.lower().split("-")[1:-1])
+
+        # Title
+        res_env_md += f"\n# {env_name}\n\n"
+        # Figure
+        res_env_md += (
+            "```{figure}"
+            + f" ../_static/environments/{env_name_snake_case}.jpg"
+            + f" \n:width: 300px\n:alt: {env_name}\n```\n\n"
+        )
+        # Docstring
+        res_env_md += f"{docstring}\n"
+
+    file_path = os.path.join(
+        os.path.dirname(os.path.dirname(__file__)),
+        "environments",
+        f"{env_name_snake_case}.md",
+    )
+
+    file = open(file_path, "w+", encoding="utf-8")
+    file.write(res_env_md)
+    file.close()

docs/_scripts/move_404.py

@@ -0,0 +1,14 @@
+import sys
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Provide a path")
+    filePath = sys.argv[1]
+
+    with open(filePath, "r+") as fp:
+        content = fp.read()
+        content = content.replace('href="../', 'href="/').replace('src="../', 'src="/')
+        fp.seek(0)
+        fp.truncate()
+
+        fp.write(content)

docs/conf.py

@@ -0,0 +1,81 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+from typing import Any, Dict
+
+import gym_miniworld
+
+project = "Miniworld"
+copyright = "2022 Farama Foundation"
+author = "Farama Foundation"
+
+# The full version, including alpha/beta/rc tags
+release = gym_miniworld.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "myst_parser",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# Napoleon settings
+napoleon_use_ivar = True
+napoleon_use_admonition_for_references = True
+# See https://github.com/sphinx-doc/sphinx/issues/9119
+napoleon_custom_sections = [("Returns", "params_style")]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+html_title = "Miniworld Documentation"
+html_baseurl = "https://miniworld.farama.org"
+html_copy_source = False
+html_favicon = "_static/img/miniworld-favicon.png"
+html_theme_options = {
+    "light_logo": "img/miniworld.svg",
+    "dark_logo": "img/miniworld-white.svg",
+    "gtag": "",
+}
+html_context: Dict[str, Any] = {}
+html_context["conf_py_path"] = "/docs/"
+html_context["display_github"] = True
+html_context["github_user"] = "Farama-Foundation"
+html_context["github_repo"] = "Miniworld"
+html_context["github_version"] = "master"
+html_context["slug"] = "miniworld"
+
+html_static_path = ["_static"]
+html_css_files = []