Add docs versioning and release notes (#319)

.github/workflows/gh-pages.yml

@@ -1,49 +1,49 @@
-name: Deploy Docs
-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 dependencies
-        run: pip install -r docs/requirements.txt
-
-      - name: Register Envs
-        run: pip install -e .
-
-      - name: Build Envs Docs
-        run: python docs/scripts/gen_mds.py
-
-      - name: Build Envs Display
-        run: python docs/scripts/gen_envs_display.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/move404.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: |
-            *.*.*/
+name: Build main branch documentation website
+on:
+  push:
+    branches: [master]
+permissions:
+  contents: write
+jobs:
+  docs:
+    name: Generate Website
+    runs-on: ubuntu-latest
+    env:
+      SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    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: Register Envs
+        run: pip install -e .
+
+      - name: Build Envs Docs
+        run: python docs/scripts/gen_mds.py
+
+      - name: Build Envs Display
+        run: python docs/scripts/gen_envs_display.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
+          target-folder: main
+          clean: false

.github/workflows/build-docs-version.yml

@@ -0,0 +1,62 @@
+name: Docs Versioning
+on:
+  push:
+    tags:
+      - 'v?*.*.*'
+permissions:
+  contents: write
+jobs:
+  docs:
+    name: Generate Website for new version
+    runs-on: ubuntu-latest
+    env:
+      SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+            python-version: '3.9'
+
+      - name: Get tag
+        id: tag
+        uses: dawidd6/action-get-tag@v1
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Register Envs
+        run: pip install -e .
+
+      - name: Build Envs Docs
+        run: python docs/scripts/gen_mds.py
+
+      - name: Build Envs Display
+        run: python docs/scripts/gen_envs_display.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
+          target-folder: ${{steps.tag.outputs.tag}}
+          clean: false
+
+      - name: Upload to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: _build
+          clean-exclude: |
+            *.*.*/
+            main

.github/workflows/manual-build-docs-version.yml

@@ -0,0 +1,74 @@
+name: Manual Docs Versioning
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+          description: 'Documentation version to create'
+          required: true
+      commit:
+          description: 'Commit used to build the Documentation version'
+          required: false
+      latest:
+          description: 'Latest version'
+          type: boolean
+
+permissions:
+  contents: write
+jobs:
+  docs:
+    name: Generate Website for new version
+    runs-on: ubuntu-latest
+    env:
+      SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+        if: inputs.commit == ''
+
+      - uses: actions/checkout@v3
+        if: inputs.commit != ''
+        with:
+          ref: ${{ inputs.commit }}
+
+      - uses: actions/setup-python@v4
+        with:
+            python-version: '3.9'
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Register Envs
+        run: pip install -e .
+
+      - name: Build Envs Docs
+        run: python docs/scripts/gen_mds.py
+
+      - name: Build Envs Display
+        run: python docs/scripts/gen_envs_display.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
+          target-folder: ${{ inputs.version }}
+          clean: false
+
+      - name: Upload to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        if: inputs.latest
+        with:
+          folder: _build
+          clean-exclude: |
+            *.*.*/
+            main

docs/conf.py

@@ -15,22 +15,20 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
-# TODO: change to minigrid version
-# from TODO import __version__ as minigrid_version
-
 from __future__ import annotations
 
 import os
 import sys
 from typing import Any
 
+import minigrid
+
 project = "MiniGrid"
 copyright = "2022"
 author = "Farama Foundation"
 
 # The full version, including alpha/beta/rc tags
-# TODO: change to minigrid version
-release = "1.2.1"
+release = minigrid.__version__
 
 sys.path.insert(0, os.path.abspath("../.."))
 
@@ -80,6 +78,7 @@ html_theme_options = {
     "light_logo": "img/minigrid.svg",
     "dark_logo": "img/minigrid-white.svg",
     "gtag": "G-FBXJQQLXKD",
+    "versioning": True,
 }
 html_context: dict[str, Any] = {}
 html_context["conf_py_path"] = "/docs/"
@@ -91,3 +90,7 @@ html_context["slug"] = "minigrid"
 
 html_static_path = ["_static"]
 html_css_files = []
+
+# -- Generate Changelog -------------------------------------------------
+
+sphinx_github_changelog_token = os.environ.get("SPHINX_GITHUB_CHANGELOG_TOKEN")

docs/index.md

@@ -61,6 +61,7 @@ environments/babyai/index
 :hidden:
 :caption: Development
 
+release_notes
 Github <https://github.com/Farama-Foundation/MiniGrid>
 ```
 

docs/release_notes.md

@@ -0,0 +1,12 @@
+---
+title: Release Notes
+---
+
+# Release Notes
+
+```{eval-rst}
+.. changelog::
+    :github: https://github.com/Farama-Foundation/Minigrid/releases
+    :pypi: https://pypi.org/project/minigrid/
+    :changelog-url:
+```