name: API Docs

on:
  push:
    branches:
      - main
  pull_request:

# ─────────────────────────────────────────────────────────────────────────────
# Doc-build — informational only
#
# Generates Doxygen HTML from the public headers and uploads it as an
# artifact for reviewer inspection.  Does NOT block merges:
# `continue-on-error: true` ensures warnings or extraction issues never
# fail the CI gate.  When Doxygen coverage is denser (Phase 8c), this job
# can be promoted to a hard requirement and the artifact deployed to
# Pages.
# ─────────────────────────────────────────────────────────────────────────────
jobs:
  doc-build:
    if: github.event_name == 'pull_request'
    runs-on: eulernest
    container:
      image: git.eulernest.eu/conformallab/ci-cpp:latest
    continue-on-error: true   # never block the merge
    steps:
      - uses: actions/checkout@v4

      - name: Install Doxygen
        run: apt-get update && apt-get install -y --no-install-recommends doxygen

      - name: Generate API documentation
        run: doxygen Doxyfile 2>&1 | tee doxygen.log

      - name: Summarise warnings
        if: always()
        run: |
          if [ -f doc/doxygen/doxygen-warnings.log ]; then
            warn=$(wc -l < doc/doxygen/doxygen-warnings.log)
            echo "DOC ▸ Doxygen warnings: $warn"
            head -20 doc/doxygen/doxygen-warnings.log
          fi

      - name: Upload HTML as artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: doxygen-html
          path: doc/doxygen/html/
          retention-days: 14