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>
Follow-up to the test-count centralisation + release-policy commit:
applies the findings of the parallel doc-audit.
Stale claims fixed
──────────────────
* CLAUDE.md line 14-17 (phase block summary): expanded from
"Phase 1-7 done, 8-9 planned, 10+ research" to reflect that
Phase 8a MVP + 8b-Lite + 9a + 9b are now done (v0.9.0), with
Phase 9b-analytic + 9c as the next planned milestones.
* CLAUDE.md line 251-252 (release state): "v0.7.0 ... Phase 7 next"
→ "v0.9.0 ... Phase 9c + 9b-analytic next".
* CLAUDE.md "Three geometry modes" → "Five DCE models" table.
Adds CP-Euclidean and Inversive-Distance rows with their CGAL
public entries. DOF-assignment pattern subsection rewritten to
cover vertex-only / vertex+edge / face-based assignments.
* CLAUDE.md "Newton solver" section: gradient sign and Hessian
convention for all five solvers (was: three). Replaces the
"Hessian is FD" claim for HyperIdeal with the block-FD note
(Phase 9b shipped).
* CLAUDE.md "Known quirks": stale GTEST_SKIP entry removed (v0.9.0
cleaned up the HDS-port stubs).
* README.md line 86: "all 24 headers with descriptions" →
"all public headers with descriptions" (was undercounting).
Missing entries added — `doc/api/headers.md`
─────────────────────────────────────────────
* New section **"Circle-packing functionals (Phase 9a)"** with
`cp_euclidean_functional.hpp` and `inversive_distance_functional.hpp`.
* New section **"Math utilities"** documenting four previously-
undocumented public helpers: `matrix_utility.hpp`,
`projective_math.hpp`, `p2_utility.hpp`, `discrete_elliptic_utility.hpp`.
* New section **"CGAL public API (Phase 8b-Lite)"** documenting all
six new public headers under `include/CGAL/`.
* `newton_solver.hpp` row expanded to list all five Newton functions.
Header count summary (before vs after):
* Before: 24 headers in 8 sections (missing 6 of the 30 actually present).
* After: 30 headers in 11 sections (complete coverage).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
