Add GitHub Pages auto-deployment workflow

.github/workflows/docs_delete_version.yaml

@@ -0,0 +1,96 @@
+# Docs Delete Version Workflow
+# This workflow automatically deletes documentation versions when tags are deleted
+# Reference documentation:
+# - GitHub Actions: https://docs.github.com/en/actions
+# - uv package manager: https://docs.astral.sh/uv/
+# - MkDocs: https://www.mkdocs.org/
+# - Mike: https://github.com/jimporter/mike
+
+name: Docs Delete Version
+
+# Trigger conditions: runs when tags are deleted
+on:
+  delete:
+    # We will guard in the job to only run for tag deletions
+
+jobs:
+  delete_version:
+    name: Delete docs version on tag removal
+    # Only run when a tag is deleted (not branch deletion)
+    if: github.event.ref_type == 'tag'
+    # Use Ubuntu 22.04 as the runtime environment
+    runs-on: ubuntu-22.04
+
+    # Set permissions: need write permissions to update documentation
+    permissions:
+      contents: write  # Allow writing to repository content
+
+    # Concurrency control: ensures multiple workflows on the same tag do not run simultaneously
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.ref }}-delete
+      cancel-in-progress: true  # Cancel running identical workflows
+
+    steps:
+      # Step 1: Checkout code
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch complete history, some tools may require this
+
+      # Step 2: Setup Python environment
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'  # Keep consistent with requirements in pyproject.toml
+
+      # Step 3: Install uv package manager
+      # uv is an extremely fast Python package manager written in Rust
+      # Compared to pip, uv has significant advantages in dependency resolution and installation speed
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"  # Use the latest version of uv
+          enable-cache: false  # Disable built-in cache to avoid conflicts with multiple uv.lock files
+
+      # Step 4: Cache uv dependencies
+      # Caching can significantly reduce build time, especially for large projects
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            docs/.venv
+          key: ${{ runner.os }}-docs-uv-${{ hashFiles('docs/uv.lock') }}-${{ hashFiles('docs/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-docs-uv-
+            ${{ runner.os }}-uv-
+
+      # Step 5: Install dependencies and configure Git
+      - name: Install dependencies and configure Git
+        run: |
+          cd docs
+          uv sync
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # Step 6: Delete docs version with mike
+      - name: Delete docs version with mike
+        run: |
+          cd docs
+          make delete-doc-version version=${{ github.event.ref }}
+
+      # Step 7: Re-point latest alias to highest remaining tag (if any)
+      - name: Re-point latest alias to highest remaining tag (if any)
+        run: |
+          set -e
+          # Find highest remaining v* tag after deletion
+          REMAINING_TAG=$(uv run mike list | sort -V | tail -n 1)
+          if [ -z "$REMAINING_TAG" ]; then
+            echo "No remaining version tags; skipping latest alias update"
+            exit 0
+          fi
+          echo "Re-pointing latest to ${REMAINING_TAG}"
+          cd docs
+          uv run mike alias --push --update "$REMAINING_TAG" latest
+          uv run mike set-default --push latest
+

.github/workflows/docs_deploy_pages.yaml

@@ -0,0 +1,98 @@
+# Docs Deploy Pages Workflow
+# This workflow uses uv for Python dependency management and automatically builds and deploys MkDocs documentation to GitHub Pages
+# Reference documentation:
+# - GitHub Actions: https://docs.github.com/en/actions
+# - uv package manager: https://docs.astral.sh/uv/
+# - MkDocs: https://www.mkdocs.org/
+# - GitHub Pages: https://docs.github.com/en/pages
+
+name: Docs Deploy Pages
+
+# Trigger conditions: runs when pushing to a tag
+on:
+  push:
+    tags:
+      # This pattern matches release version numbers according to PEP 440 (e.g., v1.2.3, 1.2.3), excluding pre/post/dev versions
+      # Note: This is used to trigger this workflow only for release version tags
+      - 'v[0-9]*.[0-9]*.[0-9]*'
+
+jobs:
+  deploy:
+    # Use Ubuntu 22.04 as the runtime environment
+    runs-on: ubuntu-22.04
+
+    # Set permissions: need write permissions to deploy to GitHub Pages
+    permissions:
+      contents: write  # Allow writing to repository content
+      pages: write     # Allow writing to Pages
+      id-token: write  # Allow writing ID token (for authentication)
+
+    # Concurrency control: ensures multiple workflows on the same branch do not run simultaneously
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true  # Cancel running identical workflows
+
+    steps:
+      # Step 1: Checkout code
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch complete history, some tools may require this
+
+      # Step 2: Setup Python environment
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'  # Keep consistent with requirements in pyproject.toml
+
+      # Step 3: Install uv package manager
+      # uv is an extremely fast Python package manager written in Rust
+      # Compared to pip, uv has significant advantages in dependency resolution and installation speed
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"  # Use the latest version of uv
+          enable-cache: false  # Disable built-in cache to avoid conflicts with multiple uv.lock files
+
+      # Step 4: Cache uv dependencies
+      # Caching can significantly reduce build time, especially for large projects
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            docs/.venv
+          key: ${{ runner.os }}-docs-uv-${{ hashFiles('docs/uv.lock') }}-${{ hashFiles('docs/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-docs-uv-
+            ${{ runner.os }}-uv-
+
+      # Step 5: Install dependencies and configure Git
+      - name: Install dependencies and configure Git
+        run: |
+          cd docs
+          uv sync
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # Step 6: Build and deploy docs with mike
+      - name: Build and deploy docs with mike
+        run: |
+          cd docs
+          make build-doc-version version=${{ github.ref_name }}
+
+      # Step 7: Ensure CNAME exists on gh-pages branch
+      - name: Ensure CNAME on gh-pages
+        run: |
+          set -e
+          DOMAIN=$(cat docs/CNAME 2>/dev/null)
+          git fetch origin gh-pages || true
+          git switch gh-pages
+          echo "$DOMAIN" > CNAME
+          git add CNAME
+          if git diff --cached --quiet; then
+            echo "CNAME unchanged"
+          else
+            git commit -m "chore: ensure CNAME for GitHub Pages"
+            git push origin gh-pages
+          fi

docs/CNAME

@@ -0,0 +1 @@
+docs.bridgic.ai

docs/Makefile

@@ -5,6 +5,7 @@ HOST ?= 127.0.0.1
 PORT ?= 8000
 
 MKDOCS = uv run mkdocs
+MIKE = uv run mike
 
 # Generate mkdocs.yml file from API reference documentation
 gen-mkdocs-yml:
@@ -16,11 +17,28 @@ build-doc:
 	@make gen-mkdocs-yml
 	$(MKDOCS) build
 
+require-version:
+	@if [ -z "$(version)" ]; then \
+		echo "ERROR: version is required. Usage: make build-doc-version version=1.2.3"; \
+		exit 1; \
+	fi
+
+# build a specific version of the docs and point the latest alias to it
+build-doc-version: require-version
+	@make gen-mkdocs-yml
+	$(MIKE) deploy --push --update-aliases $(version) latest
+	$(MIKE) set-default --push latest
+
+# Delete a deployed docs version and point the latest alias to the next highest version
+delete-doc-version: require-version
+	@make gen-mkdocs-yml
+	$(MIKE) delete --push $(version)
+
 # Start development server
 serve-doc:
 	@uv sync
 	@make gen-mkdocs-yml
-	$(MKDOCS) serve -a $(HOST):$(PORT)
+	$(MIKE) serve -a $(HOST):$(PORT)
 
 # Clean build artifacts
 clean:

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

docs/pyproject.toml

@@ -19,4 +19,5 @@ dependencies = [
     "mkdocs-literate-nav>=0.6.2",
     "mkdocs-section-index>=0.3.10",
     "pyyaml>=6.0.2",
+    "mike>=2.1.3",
 ]

docs/scripts/mkdocs_template.yml

@@ -32,6 +32,7 @@ theme:
   name: material
   logo: assets/logo.png
   favicon: assets/favicon.ico
+  custom_dir: overrides
   features:
     # Navigation
     # navigation.instant enables client-side navigation for faster page transitions.
@@ -151,6 +152,7 @@ plugins:
             - ../bridgic-integration/llms/bridgic-llms-openai
             - ../bridgic-integration/llms/bridgic-llms-openai-like
             - ../bridgic-integration/llms/bridgic-llms-vllm
+  - mike
 
 markdown_extensions:
   # Python Markdown
@@ -215,6 +217,8 @@ extra:
     # - icon: fontawesome/brands/discord
     #   link: https://discord.gg/bridgic
   generator: false
+  version:
+    provider: mike
 
 # Developer-facing validation messages: catch broken links/anchors early without breaking builds
 validation: