Two additions that close out the reviewer-prep work cleanly:
1. doc/reviewer/hub.html + publish-workflow integration
──────────────────────────────────────────────────────
Move the hand-curated reviewer hub from the codeberg `pages`
branch (where it lived as an opaque snapshot) into the repo as
`doc/reviewer/hub.html`. `.gitea/workflows/doxygen-pages.yml`
gains a conditional `if [ -f doc/reviewer/hub.html ]; then …`
step that installs it as the publish `index.html` and demotes
the auto-generated Doxygen index to `/doxygen.html`.
Effect: merging any of the open PRs into main will trigger the
workflow, which republishes BOTH the Doxygen + the reviewer hub
together. The reviewer URL stays live across merges with zero
manual intervention.
Source-controlled benefits:
* hub edits go through normal PRs, not orphan-branch
force-pushes
* old hub versions live in git history
* the in-repo links now target `branch/main/…` instead of the
transient `preview/reviewer-snapshot-vN/…` paths
2. .gitea/workflows/perf-compile-time.yml — Linux CI bench
────────────────────────────────────────────────────────
New workflow runs on every push to main that touches the build
system or public headers. Five-step matrix measures and reports:
Run 1 cold baseline (no PCH, no Unity, no ccache)
Run 2 + PCH only
Run 3 + PCH + Unity (current default)
Run 4 + FAST_TEST_BUILD=ON (-O0 -g — Linux's expected ~40 % win)
Run 5 + ccache warm rerun (expected ≥ 90 % cache hit)
Validates the Apple-M1 predictions in doc/architecture/compile-time.md
against the Linux + g++ runner where Backend dominates more and
the Apple-clang+PCH friction that defeats ccache locally does not
apply. Job is data-collection only; never blocks a merge.
doc updates:
* doc/architecture/compile-time.md — new "Cross-platform perf bench"
section linking to the workflow + the table of macOS-vs-Linux
expected deltas.
* doc/reviewer/README.md — new "Hub-Page durability" subsection
explaining how the hub survives merges.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Completes the work begun in the previous commit on this branch. Every
public symbol under code/include/ now carries a brief Doxygen comment
(0 undocumented per scripts/doxygen-coverage.sh, with the `detail::`
implementation namespaces excluded as before).
Trajectory on this branch:
start (after Doxyfile fix): 24.0 % (165 / 437 in the no-detail set
was 105 / 437 when detail counted)
after PR #17 base commit : 42.4 % (165 / 396)
this commit : 100.0 % (396 / 396)
Files touched (all .hpp / .h headers under code/include/):
* cgal/Conformal_map_traits.h
* clausen.hpp, conformal_mesh.hpp, constants.hpp (already docd)
* cp_euclidean_functional.hpp, cut_graph.hpp, discrete_elliptic_utility.hpp
* euclidean_functional.hpp, euclidean_geometry.hpp, euclidean_hessian.hpp
* fundamental_domain.hpp, gauss_bonnet.hpp
* hyper_ideal_{functional,geometry,hessian,utility,visualization_utility}.hpp
* inversive_distance_functional.hpp, layout.hpp
* matrix_utility.hpp, mesh_builder.hpp, mesh_io.hpp
* newton_solver.hpp, p2_utility.hpp, period_matrix.hpp, projective_math.hpp
* serialization.hpp, spherical_functional.hpp, spherical_geometry.hpp
* spherical_hessian.hpp, viewer_utils.h
CI:
.gitea/workflows/doxygen-pages.yml now enforces
`scripts/doxygen-coverage.sh --threshold 100`, so any future regression
(a new public function landed without a `///` brief) fails the build
before the Doxygen HTML is published to Codeberg Pages.
Doxygen warnings remain at 0.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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>
New .gitea/workflows/doxygen-pages.yml runs on every push to main that
touches the public headers, Doxyfile, the markdown-link filter, any
doc/**/*.md, README.md, or the workflow itself. It reuses the existing
ci-cpp container image and the existing CODEBERG_TOKEN secret already
used by mirror-to-codeberg.yml — no new secret setup needed.
The job force-pushes an orphan commit to the `pages` branch on
codeberg.org/TMoussa/ConformalLabpp, which Codeberg Pages serves from
https://tmoussa.codeberg.page/ConformalLabpp/ (verified live).
README.md gains a Doxygen badge and a Documentation table row pointing
at the Pages URL. locked-vs-flexible.md (the reviewer-facing doc) is
updated to mention the Pages URL next to the Doxygen-coverage gap.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
