deploy-python-docs.yml

name: Deploy MkDocs to GitHub Pages

on:
  # Deploy docs when a version tag is pushed (e.g., 25.10.1, 25.10.1.post0)
  push:
    tags:
      - '[0-9]+.[0-9]+.[0-9]+*'

  # Allow manual trigger for testing
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy (e.g., 25.10.1, 25.10.1.post0)'
        required: true
      set_latest:
        description: 'Set as latest version?'
        required: true
        type: boolean
        default: true

permissions:
  contents: read

# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    environment:
      name: github-pages
      url: https://docs.humem.ai/arcadedb/
    env:
      DOCS_REPO: humemai/humemai-docs
      DOCS_BRANCH: main

    steps:
      - name: Checkout repository
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0  # Full history for mike versioning
          token: ${{ secrets.GITHUB_TOKEN }}
          persist-credentials: false

      - name: Set up Python
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.12'

      - name: Setup UV package manager
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        run: |
          # Same pinned version and retry pattern as the test workflows: the script is downloaded first so a retried
          # transfer is never piped half-written into sh.
          installer="$(mktemp)"
          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
          sh "$installer"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          uv --version

      - name: Validate docs token
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        run: |
          if [ -z "${{ secrets.HUMEMAI_DOCS_TOKEN }}" ]; then
            echo "HUMEMAI_DOCS_TOKEN is missing"
            exit 1
          fi

      - name: Extract version from tag or input
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        id: version
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            VERSION="${{ github.event.inputs.version }}"
            SET_LATEST="${{ github.event.inputs.set_latest }}"
          else
            # Extract version from tag (e.g., 25.10.1, 25.10.1.post0)
            VERSION="${{ github.ref_name }}"
            SET_LATEST="true"
          fi
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "set_latest=$SET_LATEST" >> $GITHUB_OUTPUT
          echo "📦 Deploying documentation version: $VERSION"

      - name: Checkout humemai-docs
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: ${{ env.DOCS_REPO }}
          ref: ${{ env.DOCS_BRANCH }}
          token: ${{ secrets.HUMEMAI_DOCS_TOKEN }}
          path: humemai-docs

      - name: Configure Git (humemai-docs)
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'
        run: |
          git -C humemai-docs config user.name "github-actions[bot]"
          git -C humemai-docs config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Deploy with mike (set as latest)
        if: (github.event_name == 'workflow_dispatch' || github.event_name == 'push') && steps.version.outputs.set_latest == 'true'
        working-directory: humemai-docs
        env:
          MIKE_VERSION: ${{ steps.version.outputs.version }}
        run: |
          # Same versions as docs-build.yml, so the deployed site is built with what CI checked. Change both together.
          # mike loads mkdocs.yml, so the theme and plugins share its environment.
          mike() {
            uvx --from "mike==2.2.0" --with "mkdocs==1.6.1" --with "mkdocs-material==9.7.7" --with "mkdocs-git-revision-date-localized-plugin==1.6.0" --with "mkdocs-macros-plugin==1.5.0" mike "$@"
          }
          mike deploy --update-aliases \
            --deploy-prefix arcadedb \
            --branch ${{ env.DOCS_BRANCH }} \
            --push \
            --config-file ../bindings/python/mkdocs.yml \
            ${{ steps.version.outputs.version }} latest \
            --title "${{ steps.version.outputs.version }}"
          mike set-default \
            --deploy-prefix arcadedb \
            --branch ${{ env.DOCS_BRANCH }} \
            --push \
            --config-file ../bindings/python/mkdocs.yml \
            latest

      - name: Deploy with mike (not latest)
        if: (github.event_name == 'workflow_dispatch' || github.event_name == 'push') && steps.version.outputs.set_latest != 'true'
        working-directory: humemai-docs
        env:
          MIKE_VERSION: ${{ steps.version.outputs.version }}
        run: |
          # Same versions as docs-build.yml, so the deployed site is built with what CI checked. Change both together.
          # mike loads mkdocs.yml, so the theme and plugins share its environment.
          mike() {
            uvx --from "mike==2.2.0" --with "mkdocs==1.6.1" --with "mkdocs-material==9.7.7" --with "mkdocs-git-revision-date-localized-plugin==1.6.0" --with "mkdocs-macros-plugin==1.5.0" mike "$@"
          }
          mike deploy \
            --deploy-prefix arcadedb \
            --branch ${{ env.DOCS_BRANCH }} \
            --push \
            --config-file ../bindings/python/mkdocs.yml \
            ${{ steps.version.outputs.version }} \
            --title "${{ steps.version.outputs.version }}"