docs: auto-generate doc/api/headers.md from Doxygen XML

Replaces the hand-maintained `doc/api/headers.md` with a generated one
sourced from each header's `\file` brief and the public symbols
extracted by Doxygen into XML.  The CI workflow regenerates it on every
push to main that touches the public headers.

New files
─────────
* scripts/gen-headers-md.py — parses doc/doxygen/xml/*.xml, groups
  headers by directory (CGAL public / CGAL internals / Core), and
  writes a markdown table with header path, first-sentence brief, and
  the public symbols declared at file scope.  Skips `detail::`
  namespaces and template-specialisation duplicates.
* scripts/regen-docs.sh — convenience wrapper:
  doxygen → gen-headers-md.py → coverage report.

Workflow changes
────────────────
.gitea/workflows/doxygen-pages.yml now:
  1. Runs `bash scripts/doxygen-coverage.sh` as an informational step
     (no fail threshold yet — the script supports `--threshold N` for
     when we're ready).
  2. Re-runs `python3 scripts/gen-headers-md.py` and warns if the
     file drifted from what's in main (operator should run
     `regen-docs.sh` locally before pushing).

Doxyfile hygiene
────────────────
`HTML_TIMESTAMP` was removed in Doxygen 1.10 → replaced with the new
`TIMESTAMP = NO` to silence the obsolete-tag warning.

Effect on the reviewer-facing landing pages
───────────────────────────────────────────
Every improvement to a `\file` brief at the top of a public header now
flows automatically into both:
  * the Doxygen HTML at https://tmoussa.codeberg.page/ConformalLabpp/
  * the markdown landing at doc/api/headers.md (rendered by Codeberg
    in the repo view)
…so writers have a single source of truth (the C++ source) and
readers see the same words in both surfaces.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitea/workflows/doxygen-pages.yml

@@ -47,6 +47,24 @@ jobs:
             head -30 doc/doxygen/doxygen-warnings.log
           fi
 
+      - name: Report Doxygen coverage
+        run: bash scripts/doxygen-coverage.sh
+
+      - 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 }}