Multiversion docs build (#3842)

* test multiversion build

* Work on multiversion build

* update refs

* cancel in progress

* add docs dir

* add version switcher

* add version switcher

* add preferred

* version banner and hacky value override...

* add release version

.github/workflows/docs.yml

@@ -6,7 +6,10 @@ on:
   push:
     branches:
       - main
-      - staging
+
+  pull_request:
+    branches:
+      - main
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -17,38 +20,64 @@ permissions:
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build-04:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        version:
+          [
+            { ref: main, dest-dir: dev },
+            { ref: "v0.4.0dev0", dest-dir: "0.4.0dev0" },
+            { ref: "v0.4.0dev1", dest-dir: "0.4.0dev1" },
+          ]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          lfs: 'true'
+          lfs: "true"
+          ref: ${{ matrix.version.ref }}
       - run: curl -LsSf https://astral.sh/uv/install.sh | sh
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: "3.11"
       - run: |
           uv sync --locked --all-extras
           source .venv/bin/activate
           poe --directory ./packages/autogen-core docs-build
-          mkdir -p docs-staging/dev/
-          mv ./packages/autogen-core/docs/build/* docs-staging/dev/
+          mkdir -p docs-staging/${{ matrix.version.dest-dir }}/
+          mv ./packages/autogen-core/docs/build/* docs-staging/${{ matrix.version.dest-dir }}/
         working-directory: ./python
+        env:
+          PY_DOCS_DIR: ${{ matrix.version.dest-dir }}/
+          PY_SWITCHER_VERSION: ${{ matrix.version.dest-dir }}
+      - uses: actions/upload-artifact@v4
+        with:
+          path: "./python/docs-staging"
+          name: "${{ matrix.version.dest-dir }}-docs"
+
+  gen-redirects:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: "true"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
       - name: generate redirects
         run: |
+          mkdir -p python/docs-staging/
           python python/packages/autogen-core/docs/redirects/redirects.py python/docs-staging
       - uses: actions/upload-artifact@v4
         with:
           path: "./python/docs-staging"
-          name: "04-docs"
+          name: "redirects"
 
   build-02:
     runs-on: ubuntu-latest
@@ -112,8 +141,8 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: [build-02, build-04]
-    if: ${{ needs.build-02.result == 'success' && needs.build-04.result == 'success' && github.ref == 'refs/heads/main' }}
+    needs: [build-02, build-04, gen-redirects]
+    if: ${{ needs.build-02.result == 'success' && needs.build-04.result == 'success' && needs.gen-redirects.result == 'success' && github.ref == 'refs/heads/main' }}
     steps:
       - uses: actions/download-artifact@v4
         with:
@@ -122,8 +151,9 @@ jobs:
       - name: Copy 02-docs
         run: |
           mkdir -p deploy/
-          cp -r artifacts/02-docs/* deploy/
-          cp -r artifacts/04-docs/* deploy/
+          for dir in artifacts/*; do
+            cp -r $dir/* deploy/
+          done
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

docs/switcher.json

@@ -0,0 +1,22 @@
+[
+    {
+        "name": "0.2 (stable)",
+        "version": "0.2-stable",
+        "url": "/autogen/0.2/"
+    },
+    {
+        "version": "dev",
+        "url": "/autogen/dev/"
+    },
+    {
+        "name": "0.4.0.dev0",
+        "version": "0.4.0.dev0",
+        "url": "/autogen/0.4.0.dev0/"
+    },
+    {
+        "name": "0.4.0.dev1",
+        "version": "0.4.0.dev1",
+        "url": "/autogen/0.4.0.dev1/",
+        "preferred": true
+    }
+]

python/packages/autogen-core/docs/src/_static/override-switcher-button.js

@@ -0,0 +1,15 @@
+// When body is ready
+document.addEventListener('DOMContentLoaded', function() {
+    // TODO: Please find a better way to override the button text in a better way...
+    // Set a timer for 3 seconds to wait for the button to be rendered.
+    setTimeout(function() {
+        // Get the button with class "pst-button-link-to-stable-version". There is only one.
+        var button = document.querySelector('.pst-button-link-to-stable-version');
+        if (!button) {
+            // If the button is not found, return.
+            return;
+        }
+        // Set the button's text to "Switch to latest dev release"
+        button.textContent = "Switch to latest dev release";
+    }, 500);
+});

python/packages/autogen-core/docs/src/conf.py

@@ -3,19 +3,21 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-import pydata_sphinx_theme
 from sphinx.application import Sphinx
 from typing import Any, Dict
 from pathlib import Path
 import sys
+import os
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import autogen_core
 
 project = "autogen_core"
 copyright = "2024, Microsoft"
 author = "Microsoft"
-version = "0.2"
+version = "0.4"
+release = autogen_core.__version__
 
 
 sys.path.append(str(Path(".").resolve()))
@@ -60,7 +62,14 @@
     "strikethrough",
 ]
 
-html_baseurl = "/autogen/dev/"
+if (path := os.getenv("PY_DOCS_DIR")) is None:
+    path = "dev"
+
+
+if (switcher_version := os.getenv("PY_SWITCHER_VERSION")) is None:
+    switcher_version = "dev"
+
+html_baseurl = f"/autogen/{path}/"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -70,7 +79,6 @@
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_sidebars = {'packages/index': []}
 
 html_logo = "_static/images/logo/logo.svg"
 html_favicon = "_static/images/logo/favicon-512x512.png"
@@ -108,10 +116,17 @@
     "footer_center": ["footer-middle-links"],
     "footer_end": ["theme-version"],
     "pygments_light_style": "xcode",
-    "pygments_dark_style": "monokai"
+    "pygments_dark_style": "monokai",
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "switcher": {
+        "json_url": "https://raw.githubusercontent.com/microsoft/autogen/refs/heads/main/docs/switcher.json",
+        "version_match": switcher_version,
+    },
+    "show_version_warning_banner": True,
+
 }
 
-html_js_files = ["custom-icon.js"]
+html_js_files = ["custom-icon.js", "override-switcher-button.js"]
 html_sidebars = {
     "packages/index": [],
 }