python_build_docs.yml

name: Build and Deploy Python Docs (Dev)

on:
  pull_request:
    types: [ opened, synchronize, closed ]
    paths:
      - '.github/actions/python-mike-*/**'
      - 'python/docs/**'
      - 'python/lib/**'
      - 'python/mkdocs.yml'
      - 'python/pyproject.toml'
  workflow_dispatch:
    inputs:
      deploy_to_dev:
        description: 'Deploy to dev alias using commit hash as version'
        required: false
        default: true
        type: boolean

jobs:
  build_docs:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Extract version
        id: version
        run: |
          # Use commit hash as version for dev deployments
          VERSION=$(git rev-parse --short HEAD)

          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
            # Use PR number as alias for PR deployments
            ALIAS="pr-${{ github.event.number }}"
          else
            # Use 'dev' for manual workflow dispatch
            ALIAS="dev"
          fi

          echo "version=$VERSION" >> $GITHUB_OUTPUT
          echo "alias=$ALIAS" >> $GITHUB_OUTPUT
          echo "Dev deployment - Version: $VERSION, Alias: $ALIAS"

      - name: Deploy docs
        uses: ./.github/actions/python-mike-deploy
        with:
          version: ${{ steps.version.outputs.alias }}
          hidden: 'true'

      - name: Comment docs preview link on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const marker = '<!-- mike-docs-preview -->';
            const alias = '${{ steps.version.outputs.alias }}';
            const version = '${{ steps.version.outputs.version }}';
            const url = `https://sift-stack.github.io/sift/python/${alias}/`;
            const body = [
              marker,
              `**Python docs preview:** ${url}`,
              ``,
              `Deployed from \`${version}\`. The link may take up to a minute to become live as GitHub Pages propagates.`,
            ].join('\n');

            const { owner, repo } = context.repo;
            const issue_number = context.issue.number;

            const { data: comments } = await github.rest.issues.listComments({
              owner, repo, issue_number, per_page: 100,
            });
            const existing = comments.find(c => c.body && c.body.includes(marker));

            if (existing) {
              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
            } else {
              await github.rest.issues.createComment({ owner, repo, issue_number, body });
            }

  cleanup_docs:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Delete PR docs
        uses: ./.github/actions/python-mike-delete
        with:
          version: pr-${{ github.event.number }}