static.yml

# Workflow for deploying static content to GitHub Pages with PR previews
name: Deploy Documentation
on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
  # Runs on pull requests for preview builds
  pull_request:
    branches: ["main"]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to build preview for (leave empty for current branch)'
        required: false
        type: string

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write
  pull-requests: write

# Allow only one concurrent deployment per branch/PR, cancel in-progress runs
concurrency:
  group: "pages-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || 'pages-main' }}"
  cancel-in-progress: false

jobs:
  # Build job - runs for both main branch and PRs
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Set up python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
          
      - name: Install dependencies
        run: |
          sudo apt install pandoc
          pip install -r requirements.txt 
          pip install ipykernel rdkit cairosvg pymzml
          pip install .
          
      - name: Build Documentation
        run: sphinx-build -b html ./docs ./_build
        
      - name: Copy binder files
        run: cp -r ./.binder ./_build
        
      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation-${{ github.sha }}
          path: _build/
          retention-days: 30

  # Deploy to main GitHub Pages (only for main branch)
  deploy-main:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: documentation-${{ github.sha }}
          path: _build/
          
      - name: Setup Pages
        uses: actions/configure-pages@v5
        
      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: _build/
          
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # Deploy PR preview using subdirectories in gh_pages
  deploy-preview:
    if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr_number != '')
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout gh_pages branch
        uses: actions/checkout@v4
        with:
          ref: gh_pages
          token: ${{ secrets.GITHUB_TOKEN }}
          
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: documentation-${{ github.sha }}
          path: _temp_build/
          
      - name: Get PR number
        id: pr_info
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "pr_number=${{ github.event.number }}" >> $GITHUB_OUTPUT
          else
            echo "pr_number=${{ github.event.inputs.pr_number }}" >> $GITHUB_OUTPUT
          fi
          
      - name: Deploy PR preview to subdirectory
        run: |
          PR_NUMBER="${{ steps.pr_info.outputs.pr_number }}"
          PR_DIR="pr-${PR_NUMBER}"
          
          # Remove existing PR directory if it exists
          rm -rf "$PR_DIR"
          
          # Create PR directory and copy files
          mkdir -p "$PR_DIR"
          cp -r _temp_build/* "$PR_DIR/"
          
          # Clean up temp directory
          rm -rf _temp_build
          
          # Configure git
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          
          # Add and commit changes
          git add "$PR_DIR"
          git commit -m "Deploy PR #${PR_NUMBER} preview [skip ci]" || echo "No changes to commit"
          
          # Push to gh_pages
          git push origin gh_pages
          
      - name: Comment on PR with preview link
        if: github.event_name == 'pull_request' || github.event.inputs.pr_number != ''
        uses: actions/github-script@v7
        with:
          script: |
            const prNumber = "${{ steps.pr_info.outputs.pr_number }}";
            const repoOwner = context.repo.owner;
            const repoName = context.repo.repo;
            const previewUrl = `https://${repoOwner}.github.io/${repoName}/pr-${prNumber}/`;
            
            // Check if we already commented
            const comments = await github.rest.issues.listComments({
              owner: repoOwner,
              repo: repoName,
              issue_number: prNumber,
            });
            
            const botComment = comments.data.find(comment => 
              comment.user.login === 'github-actions[bot]' && 
              comment.body.includes('📖 Documentation Preview')
            );
            
            const commentBody = `📖 **Documentation Preview**
            
            The documentation for this PR has been built and is available at:
            🔗 **[View Preview](${previewUrl})**
            
            This preview will be updated automatically when you push new commits to this PR.
            
            ---
            *Preview built from commit: \`${context.sha.substring(0, 7)}\`*`;
            
            if (botComment) {
              // Update existing comment
              await github.rest.issues.updateComment({
                owner: repoOwner,
                repo: repoName,
                comment_id: botComment.id,
                body: commentBody
              });
            } else {
              // Create new comment
              await github.rest.issues.createComment({
                owner: repoOwner,
                repo: repoName,
                issue_number: prNumber,
                body: commentBody
              });
            }

  # Cleanup old PR preview branches
  cleanup-previews:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0
          
      - name: Delete PR preview directory
        run: |
          PR_NUMBER="${{ github.event.number }}"
          PR_DIR="pr-${PR_NUMBER}"
          
          # Checkout gh_pages branch
          git checkout gh_pages
          
          # Remove PR directory if it exists
          if [ -d "$PR_DIR" ]; then
            rm -rf "$PR_DIR"
            git add "$PR_DIR"
            git commit -m "Remove PR #${PR_NUMBER} preview [skip ci]"
            git push origin gh_pages
            echo "Deleted preview directory: $PR_DIR"
          else
            echo "Preview directory $PR_DIR not found"
          fi
          
      - name: Comment cleanup notification
        uses: actions/github-script@v7
        with:
          script: |
            const prNumber = context.payload.number;
            
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: prNumber,
              body: `🧹 **Preview Cleanup**
              
              The documentation preview for this PR has been cleaned up and is no longer available.`
            });