Skip to content

A programming framework for agentic AI

Multiversion docs build (#3842)

Jack Gerritsd3d736510ce4
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 17996088f..51faf7cf1 100644
--- a/.github/workflows/docs.yml
+++ b/.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
diff --git a/docs/switcher.json b/docs/switcher.json
new file mode 100644
index 000000000..bea742de3
--- /dev/null
+++ b/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
+ }
+]
diff --git a/python/packages/autogen-core/docs/src/_static/override-switcher-button.js b/python/packages/autogen-core/docs/src/_static/override-switcher-button.js
new file mode 100644
index 000000000..5406cd07e
--- /dev/null
+++ b/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);
+});
diff --git a/python/packages/autogen-core/docs/src/conf.py b/python/packages/autogen-core/docs/src/conf.py
index 489e6534d..11341873d 100644
--- a/python/packages/autogen-core/docs/src/conf.py
+++ b/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 @@ myst_enable_extensions = [
"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_title = "AutoGen"
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 @@ html_theme_options = {
"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": [],
}