name: API Docs

# Trigger: write "/docs" as a comment on any pull request.
# Also available via workflow_dispatch for manual runs outside a PR context.

on:
  issue_comment:
    types: [created]
  workflow_dispatch: {}

# ─────────────────────────────────────────────────────────────────────────────
# Doc-build — informational only
#
# Generates Doxygen HTML from the public headers and reports warning
# statistics.  Does NOT block merges: `continue-on-error: true` ensures
# warnings or extraction issues never fail.
#
# Trigger: "/docs" PR comment (or workflow_dispatch for manual runs).
# Checkout uses refs/pull/N/head when triggered via comment.
# ─────────────────────────────────────────────────────────────────────────────
jobs:
  doc-build:
    if: |
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request != null &&
       contains(github.event.comment.body, '/docs'))
    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
        with:
          ref: ${{ github.event_name == 'issue_comment' && format('refs/pull/{0}/head', github.event.issue.number) || github.ref }}

      - 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"
            echo ""
            echo "First 20 warnings:"
            head -20 doc/doxygen/doxygen-warnings.log
          else
            echo "DOC ▸ No warning log produced — check that Doxyfile WARN_LOGFILE points to doc/doxygen/doxygen-warnings.log"
          fi

      - name: Report HTML output
        if: always()
        run: |
          if [ -d doc/doxygen/html ]; then
            files=$(find doc/doxygen/html -type f | wc -l)
            size=$(du -sh doc/doxygen/html | cut -f1)
            echo "DOC ▸ HTML output: $files files, $size total"
          fi