Uni-Lab-OS/.github/workflows/deploy-docs.yml

name: Deploy Docs

on:
  # 在 CI Check 成功后自动触发（仅 main 分支）
  workflow_run:
    workflows: ["CI Check"]
    types: [completed]
    branches: [main]
  # 手动触发
  workflow_dispatch:
    inputs:
      branch:
        description: '要部署文档的分支'
        required: false
        default: 'main'
        type: string
      deploy_to_pages:
        description: '是否部署到 GitHub Pages'
        required: false
        default: true
        type: boolean

# 设置 GITHUB_TOKEN 权限以部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许一个并发部署，跳过正在进行和最新排队之间的运行
# 但是不取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  # Build documentation
  build:
    # 只在以下情况运行：
    # 1. workflow_run 触发且 CI Check 成功
    # 2. 手动触发
    if: |
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          # workflow_run 时使用触发工作流的分支，手动触发时使用输入的分支
          ref: ${{ github.event.workflow_run.head_branch || github.event.inputs.branch || github.ref }}
          fetch-depth: 0

      - name: Setup Miniforge (with mamba)
        uses: conda-incubator/setup-miniconda@v3
        with:
          miniforge-version: latest
          use-mamba: true
          python-version: '3.11.14'
          channels: conda-forge,robostack-staging,uni-lab,defaults
          channel-priority: flexible
          activate-environment: unilab
          auto-update-conda: false
          show-channel-urls: true

      - name: Install unilabos and dependencies
        run: |
          echo "Installing unilabos and dependencies to unilab environment..."
          echo "Using mamba for faster and more reliable dependency resolution..."
          mamba install -n unilab uni-lab::unilabos -c uni-lab -c robostack-staging -c conda-forge -y

      - name: Install latest unilabos from source
        run: |
          echo "Uninstalling existing unilabos..."
          mamba run -n unilab pip uninstall unilabos -y || echo "unilabos not installed via pip"
          echo "Installing unilabos from source..."
          mamba run -n unilab pip install .
          echo "Verifying installation..."
          mamba run -n unilab pip show unilabos

      - name: Install documentation dependencies
        run: |
          echo "Installing documentation build dependencies..."
          mamba run -n unilab pip install -r docs/requirements.txt

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
        if: |
          github.event.workflow_run.head_branch == 'main' ||
          (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')

      - name: Build Sphinx documentation
        run: |
          cd docs
          # Clean previous builds
          rm -rf _build
          # Build HTML documentation in conda environment
          mamba run -n unilab python -m sphinx -b html . _build/html -v

      - name: Check build results
        run: |
          echo "Documentation build completed, checking output directory:"
          ls -la docs/_build/html/
          echo "Checking for index.html:"
          test -f docs/_build/html/index.html && echo "✓ index.html exists" || echo "✗ index.html missing"

      - name: Upload build artifacts
        uses: actions/upload-pages-artifact@v4
        if: |
          github.event.workflow_run.head_branch == 'main' ||
          (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
        with:
          path: docs/_build/html

  # Deploy to GitHub Pages
  deploy:
    if: |
      github.event.workflow_run.head_branch == 'main' ||
      (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4