ConformalLabpp/.gitea/workflows/doxygen-pages.yml

name: Doxygen → Codeberg Pages (manual-only)

# Auto-publish Doxygen HTML to https://tmoussa.codeberg.page/ConformalLabpp/
# every time the public API or docs source changes on main.
#
# Pattern: mirrors mirror-to-codeberg.yml — reuses the existing
# CODEBERG_TOKEN secret + HTTPS push.  No new secret setup required.
#
# ─── DISABLED 2026-05-26 ───────────────────────────────────────────────────
# The auto-publish trigger is intentionally disabled.  Background: the
# `pages` branch on codeberg went into an inconsistent state during the
# v0.10.0 PR-merge sequence (the cleanup deleted preview branches and the
# resulting force-pushes left the pages branch unreachable for the CI's
# HTTPS push).  Until the underlying push step is verified to work cleanly
# from CI again, the workflow is restricted to `workflow_dispatch` only —
# meaning: manual republication via the Gitea Actions UI, no automatic
# overwrite of the manually-curated pages branch on every main push.
#
# The pages branch currently serves the v6 reviewer hub HTML
# (`doc/reviewer/hub.html` source-of-truth) plus the Doxygen output at
# /doxygen.html.  Both are stable and survive merges as long as nothing
# pushes to the pages branch.
#
# To re-enable auto-publish later: uncomment the `push:` block below, run
# a manual dispatch first to verify, then watch a normal merge.
#
# on:
#   push:
#     branches:
#       - main
#     paths:
#       - "code/include/**"
#       - "Doxyfile"
#       - "scripts/doxygen-md-filter.sh"
#       - "doc/**/*.md"
#       - "README.md"
#       - "CLAUDE.md"
#       - ".gitea/workflows/doxygen-pages.yml"
on:
  workflow_dispatch: {}

jobs:
  publish:
    runs-on: eulernest
    container:
      image: git.eulernest.eu/conformallab/ci-cpp:latest

    steps:
      - uses: actions/checkout@v4

      - name: Configure CMake (Doxygen target only — no compiler needed)
        run: cmake -S code -B build

      - name: Build Doxygen HTML
        run: |
          cmake --build build --target doc
          test -f doc/doxygen/html/index.html
          warnings=$(wc -l < doc/doxygen/doxygen-warnings.log)
          echo "DOC ▸ Doxygen warnings: $warnings"
          if [ "$warnings" -gt 0 ]; then
            echo "::warning::Doxygen produced $warnings warning(s) — review doc/doxygen/doxygen-warnings.log"
            head -30 doc/doxygen/doxygen-warnings.log
          fi

      - name: Enforce Doxygen coverage 100%
        # Coverage is measured against every public symbol under
        # code/include/ (the `detail::` namespaces are excluded).  As of
        # the `docs/doxygen-coverage-100` PR the baseline is 100 %, so
        # the gate fires only on regressions.
        run: bash scripts/doxygen-coverage.sh --threshold 100

      - name: Regenerate doc/api/headers.md from XML
        run: |
          python3 scripts/gen-headers-md.py
          # If the auto-generated headers.md drifted from main, note it.
          # This job runs on every main push so a drift only persists
          # for the duration of one push — the next push that lands
          # will fold the new headers.md back into main (via the
          # codeberg pages branch).  For deterministic regeneration
          # within main itself, run `bash scripts/regen-docs.sh`
          # locally before pushing.
          if ! git diff --quiet -- doc/api/headers.md; then
            echo "::warning::doc/api/headers.md drifted — run scripts/regen-docs.sh locally and commit before next push"
            git --no-pager diff -- doc/api/headers.md | head -30
          fi

      - name: Publish HTML to codeberg pages branch
        env:
          CODEBERG_TOKEN: ${{ secrets.CODEBERG_TOKEN }}
        run: |
          set -eu
          # Build the publish payload in a clean scratch dir so the
          # orphan branch contains only the reviewer hub + Doxygen
          # output (and a marker README), never any build/source
          # artefacts.
          publish_dir=$(mktemp -d)
          cp -r doc/doxygen/html/. "$publish_dir/"

          # ── Reviewer hub override ─────────────────────────────────
          # If doc/reviewer/hub.html is present, install it as the
          # publish landing page and demote the auto-generated Doxygen
          # index to /doxygen.html.  The hub is hand-curated and lives
          # under source control; this step keeps it visible after
          # every push to main, surviving the auto-publish cycle.
          if [ -f doc/reviewer/hub.html ]; then
              mv "$publish_dir/index.html" "$publish_dir/doxygen.html"
              cp doc/reviewer/hub.html "$publish_dir/index.html"
              echo "DOC ▸ reviewer hub installed; Doxygen index now at /doxygen.html"
          fi

          cat > "$publish_dir/README.txt" <<EOF
          conformallab++ — Doxygen HTML API documentation + reviewer hub.
          Auto-generated by .gitea/workflows/doxygen-pages.yml from
          commit ${GITHUB_SHA:-$(git rev-parse HEAD)} on $(date -Iseconds).
          Source: https://codeberg.org/TMoussa/ConformalLabpp
          Reviewer hub: doc/reviewer/hub.html (in-repo)
          Doxygen index: /doxygen.html
          EOF

          cd "$publish_dir"
          git init -q -b pages
          git config user.email "ci@eulernest"
          git config user.name  "conformallab CI"
          git add -A
          git commit -q -m "Auto-publish: Doxygen HTML for ${GITHUB_SHA:-HEAD}"
          # Force-push: the pages branch is a publish target, history
          # is not interesting (we only ever serve the latest snapshot).
          git push -f \
            "https://TMoussa:${CODEBERG_TOKEN}@codeberg.org/TMoussa/ConformalLabpp.git" \
            pages:pages