From d3d736510ce44f7ee7c3dc9a8a1091ca1c43dacc Mon Sep 17 00:00:00 2001 From: Jack Gerrits Date: Tue, 22 Oct 2024 17:37:10 -0400 Subject: [PATCH] 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 | 58 ++++++++++++++----- docs/switcher.json | 22 +++++++ .../src/_static/override-switcher-button.js | 15 +++++ python/packages/autogen-core/docs/src/conf.py | 27 +++++++-- 4 files changed, 102 insertions(+), 20 deletions(-) create mode 100644 docs/switcher.json create mode 100644 python/packages/autogen-core/docs/src/_static/override-switcher-button.js diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 17996088f515..51faf7cf1c35 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 000000000000..bea742de395c --- /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 000000000000..5406cd07e4f3 --- /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 489e6534d9cf..11341873d141 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 @@ "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": [], }