build_docs.yml

name: Build and Deploy Docs

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  build_docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install -U sphinx sphinx-rtd-theme sphinxcontrib-napoleon sphinx_copybutton lightning psutil

      - name: Build Documentation
        run: |
          sphinx-build -b html docs/source public/
          if [ ! -d "public" ]; then
            echo "Error: Documentation build failed. 'public/' directory not found."
            exit 1
          fi

      - name: Deploy to GitHub Pages
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"

          # Save generated documentation
          if [ -d "public" ]; then
            echo "Saving generated documentation..."
            ls -al public/
            mv public /tmp/public_docs
          else
            echo "Error: 'public/' directory does not exist. Exiting."
            exit 1
          fi

          # Clean and switch to gh-pages branch
          git reset --hard
          git clean -fdx

          if git ls-remote --exit-code origin gh-pages; then
            git fetch origin gh-pages
            git checkout gh-pages
          else
            git checkout --orphan gh-pages
          fi

          # Clean old content and restore new documentation
          echo "Cleaning old content..."

          find . -maxdepth 1 ! -name '.git' ! -name '.' -exec rm -rf {} +
          echo "Restoring new documentation..."
          mv /tmp/public_docs/* .

          # Deploy to GitHub Pages
          touch .nojekyll
          git add .
          if git diff --cached --quiet; then
            echo "No changes to commit. Skipping deployment."
            exit 0
          else
            git commit -m "Deploy updated documentation to GitHub Pages from commit $GITHUB_SHA"
            git push origin gh-pages --force
          fi