name: Deploy GitHub Pages

# Builds Doxygen + deploys to GitHub Pages.  The canonical site lives
# at https://gburd.github.io/lime/ (or the custom domain configured
# in repo settings).  Codeberg Pages is the parallel deployment from
# .forgejo/workflows/pages.yml; both serve the same Doxygen output
# from the same `main`-branch sources.

on:
  push:
    branches: [main]
    paths:
      - 'include/**'
      - 'src/**'
      - 'docs/**'
      - '.github/workflows/pages.yml'
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Install doxygen
      run: sudo apt-get update && sudo apt-get install -y doxygen

    - name: Generate API docs
      working-directory: docs
      run: doxygen Doxyfile 2>../doxygen-warnings.txt

    - name: Report doxygen warning count
      # Does not fail the build on existing warnings (there's a known
      # backlog documented in TESTING.md / Doxyfile).  Surfaces the
      # count so a sudden jump is visible in CI logs, and we can
      # flip this to a hard fail once the backlog reaches zero.
      run: |
        count=$(wc -l < doxygen-warnings.txt)
        echo "::notice::Doxygen produced ${count} warning lines"
        if [ "${count}" -gt 0 ]; then
          echo "First 20:"
          head -20 doxygen-warnings.txt
        fi

    - name: Verify site contents
      run: |
        # Smoke check: index.html exists and references the project.
        test -s docs/api/html/index.html
        grep -q -i 'lime' docs/api/html/index.html
        echo "Doxygen site built ($(find docs/api/html -type f | wc -l) files)"

    - name: Upload Pages artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: docs/api/html

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4