name: Deploy Docs

on:
  push:
    branches: [main]
  pull_request:
    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:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.branch || github.ref }}

      - name: Setup Python environment
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y pandoc

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          # Install package in development mode to get version info
          pip install -e .
          # Install documentation dependencies
          pip install -r docs/requirements.txt

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
        if: github.ref == 'refs/heads/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
          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@v3
        if: github.ref == 'refs/heads/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.ref == 'refs/heads/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