Add docs (#13)

.github/workflows/build-docs.yml

@@ -0,0 +1,42 @@
+name: Build Documentation website
+on:
+  push:
+    branches: [main]
+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 dependencies
+        run: pip install -r docs/requirements.txt
+        
+      - name: Install Gymnasium
+        run: pip install .
+      
+      - 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
+          clean-exclude: |
+            *.*.*/

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
     hooks:
       - id: codespell
         args:
-          - --ignore-words-list=nd,reacher,thist,ths, ure, referenc
+          - --ignore-words-list=nd,reacher,thist,ths, ure, referenc,wile
   - repo: https://gitlab.com/PyCQA/flake8
     rev: 4.0.1
     hooks:
@@ -30,7 +30,7 @@ repos:
     rev: 6.1.1  # pick a git hash / tag to point to
     hooks:
       - id: pydocstyle
-        exclude: ^(gymnasium/version.py)|(gymnasium/envs/)|(tests/)
+        exclude: ^(gymnasium/version.py)|(gymnasium/envs/)|(tests/)|(docs/)
         args:
           - --source
           - --explain

docs/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+__pycache__
+.vscode/
+build/
+_build/

docs/404.md

@@ -0,0 +1,7 @@
+---
+hide-toc: true
+---
+
+# 404
+
+## Page Not 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,51 @@
+# Gymnasium-docs
+
+This folder contains the documentation for [Gymnasium](https://github.com/Farama-Foundation/gymnasium).
+
+If you are modifying a non-environment page or an atari environment page, please PR this repo. Otherwise, follow the steps below:
+
+## Instructions for modifying environment pages
+
+### Editing an environment page
+
+If you are editing an Atari environment, directly edit the Markdown file in this repository. 
+
+Otherwise, fork Gymnasium and edit the docstring in the environment's Python file. Then, pip install your Gymnasium fork and run `docs/scripts/gen_mds.py` in this repo. This will automatically generate a Markdown documentation file for the environment.
+
+### Adding a new environment
+
+#### Atari env
+
+For Atari envs, add a Markdown file into `pages/environments/atari` then complete the **other steps**.
+
+#### Non-Atari env
+
+Ensure the environment is in Gymnasium (or your fork). Ensure that the environment's Python file has a properly formatted markdown docstring. Pip install Gymnasium (or your fork) then run `docs/scripts/gen_mds.py`. This will automatically generate an md page for the environment. Then complete the [other steps](#other-steps).
+
+#### Other steps
+
+- Add the corresponding gif into the `docs/_static/videos/{ENV_TYPE}` folder, where `ENV_TYPE` is the category of your new environment (e.g. mujoco). Follow snake_case naming convention. Alternatively, run `docs/scripts/gen_gifs.py`.
+- Edit `docs/environments/{ENV_TYPE}/index.md`, and add the name of the file corresponding to your new environment to the `toctree`.
+
+## Build the Documentation
+
+Install the required packages and Gymnasium (or your fork):
+
+```
+pip install -r requirements.txt
+pip install gymnasium
+```
+
+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/_static/css/custom.css

@@ -0,0 +1,97 @@
+h1 {
+    font-size: 2.25rem;
+}
+
+h2 {
+    font-size: 1.75rem;
+}
+
+h3 {
+    font-size: 1.45rem;
+}
+
+.cookie_alert {
+    position: fixed;
+    display: flex;
+    width: 100%;
+    min-height: 70px;
+    background-color: var(--color-background-secondary);
+    color: var(--color-foreground-primary);
+    border-top: 1px solid var(--color-background-border);
+    bottom: 0;
+    left: 0;
+    z-index: 99999;
+}
+
+.cookie_container {
+    display: flex;
+    align-items: center;
+    width: 700px;
+    max-width: calc(100% - 28px);
+    margin: auto;
+}
+
+.cookie_alert p {
+    flex: 1;
+}
+
+.cookie_alert button {
+    background-color: transparent;
+    border: none;
+    width: 26px;
+    height: 26px;
+    padding: 0;
+    cursor: pointer;
+}
+
+.cookie_alert button svg .cls-1 {
+     stroke: var(--color-foreground-primary);
+}
+
+.cookie_alert button svg {
+    width: 100%;
+}
+
+.sidebar-logo-container {
+    display: flex;
+    height: 100px;
+}
+
+/*=======================
+Envinronments grid
+========================*/
+.env-grid {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    width: 100%;
+    box-sizing: border-box;
+}
+.env-grid__cell {
+    display: flex;
+    flex-direction: column;
+    width: 180px;
+    height: 180px;
+    padding: 10px;
+}
+.cell__image-container {
+    display: flex;
+    height: 148px;
+    justify-content: center;
+}
+.cell__image-container img {
+    max-height: 100%;
+}
+.cell__title {
+    display: flex;
+    justify-content: center;
+    text-align: center;
+    align-items: flex-end;
+    height: 32px;
+    line-height: 16px;
+}
+.more-btn {
+    width: 240px;
+    margin: 12px auto;
+    display: block;
+}

docs/_static/css/env_pages.css

@@ -0,0 +1,35 @@
+.env-grid {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    width: 100%;
+    box-sizing: border-box;
+}
+.env-grid__cell {
+    display: flex;
+    flex-direction: column;
+    width: 180px;
+    height: 180px;
+    padding: 10px;
+}
+.cell__image-container {
+    display: flex;
+    height: 148px;
+    justify-content: center;
+}
+.cell__image-container img {
+    max-height: 100%;
+}
+.cell__title {
+    display: flex;
+    justify-content: center;
+    text-align: center;
+    align-items: flex-end;
+    height: 32px;
+    line-height: 16px;
+}
+.more-btn {
+    width: 240px;
+    margin: 12px auto;
+    display: block;
+}

docs/_static/img/github_icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="72" height="72" viewBox="0 0 24 24" fill="none" stroke="white" stroke-width="0.5" stroke-linecap="round" stroke-linejoin="round" class="feather feather-github"><path d="M9 19c-5 1.5-5-2.5-7-3m14 6v-3.87a3.37 3.37 0 0 0-.94-2.61c3.14-.35 6.44-1.54 6.44-7A5.44 5.44 0 0 0 20 4.77 5.07 5.07 0 0 0 19.91 1S18.73.65 16 2.48a13.38 13.38 0 0 0-7 0C6.27.65 5.09 1 5.09 1A5.07 5.07 0 0 0 5 4.77a5.44 5.44 0 0 0-1.5 3.78c0 5.42 3.3 6.61 6.44 7A3.37 3.37 0 0 0 9 18.13V22"></path></svg>