Docs Versioning (#73)

.github/workflows/build-docs.yml

@@ -1,4 +1,4 @@
-name: Build Documentation website
+name: Build main branch documentation website
 on:
   push:
     branches: [main]
@@ -41,5 +41,5 @@ jobs:
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: _build
-          clean-exclude: |
+          target-folder: main
-            *.*.*/
+          clean: false

.github/workflows/docs-manual-versioning.yml

@@ -0,0 +1,63 @@
+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
+    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 Library
+        run: pip install -e .
+
+      - name: Install dependencies
+        run: pip install -r ./docs/requirements.txt
+
+      - name: Build
+        run: sphinx-build -b dirhtml -v docs _build
+
+      - name: Remove CNAME
+        run: rm -f ./_build/CNAME
+
+      - 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

.github/workflows/docs-versioning.yml

@@ -0,0 +1,53 @@
+name: Docs Versioning
+on:
+  push:
+    tags:
+      - 'v?*.*.*'
+permissions:
+  contents: write
+jobs:
+  docs:
+    name: Generate Website for new version
+    runs-on: ubuntu-latest
+    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
+        with:
+          strip_v: true
+
+      - name: Install Library
+        run: pip install -e .
+
+      - name: Install dependencies
+        run: pip install -r ./docs/requirements.txt
+
+      - name: Build
+        run: sphinx-build -b dirhtml -v docs _build
+
+      - name: Remove CNAME
+        run: rm -f ./_build/CNAME
+
+      - 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

docs/conf.py

@@ -77,6 +77,7 @@ html_theme_options = {
     "gtag": "G-6H9C8TWXZ8",
     "description": "A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym)",
     "image": "img/gymnasium-github.png",
+    "versioning": True,
 }
 html_context: Dict[str, Any] = {}
 html_context["conf_py_path"] = "/docs/"

docs/index.md

@@ -75,4 +75,5 @@ tutorials/*
 :caption: Development
 
 Github <https://github.com/Farama-Foundation/Gymnasium>
+Contribute to the Docs <https://github.com/Farama-Foundation/Gymnasium/blob/main/docs/README.md>
 ```