deploy-docs.yml

name: Build and Deploy Documentation

on:
  push:
    branches: [main]
  schedule:
    # Rebuild weekly to catch UCLCHEM updates
    - cron: '0 0 * * 0'  # Every Sunday at midnight UTC
  workflow_dispatch:  # Allow manual triggers
    inputs:
      github_token:
        description: 'GitHub token for artifact access'
        required: false

permissions:
  contents: read
  pages: write
  id-token: write

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

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout documentation repository
      uses: actions/checkout@v4
      with:
        path: 'uclchem.github.io'
    
    - name: Checkout UCLCHEM repository
      uses: actions/checkout@v4
      with:
        repository: 'uclchem/uclchem'
        path: 'uclchem'
        fetch-depth: 0  # Fetch all history for all branches and tags

    - name: Prepare UCLCHEM repository refs
      working-directory: ./uclchem
      run: |
        # Create local branches for specific refs we need
        # This makes act behave like GitHub Actions
        git fetch origin develop:develop 2>/dev/null || echo "develop already exists"
        echo "Available refs:"
        git branch
        git tag | grep -E "^v3\." | tail -5

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'
        cache: 'pip'

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

    - name: Install documentation dependencies
      working-directory: ./uclchem.github.io
      run: |
        pip install -r requirements.txt

    - name: Build multi-version documentation with artifacts
      working-directory: ./uclchem.github.io
      env:
        GITHUB_TOKEN: ${{ github.token }}
      run: |
        echo "Building multi-version documentation..."
        echo "Using enhanced artifact system for pre-executed notebooks"
        echo "Artifact sources: GitHub Releases + GitHub Actions"
        echo "Fallback: Git extraction (notebooks without outputs)"
        
        python3 scripts/build_docs.py \
          --config scripts/versions.yaml \
          --github-token "$GITHUB_TOKEN" \
          --uclchem-repo ../uclchem \
          --ci

    - name: Upload Pages artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./uclchem.github.io/_build/html

  deploy:
    needs: build-and-deploy
    if: github.ref == 'refs/heads/main'
    
    permissions:
      pages: write
      id-token: write
    
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    runs-on: ubuntu-latest
    
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4