From 0b1bf07232fb22041c25ef2faf271c66c8a8f79f Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sat, 23 May 2026 23:09:40 +0200 Subject: [PATCH 1/3] docs: fix 2 broken internal links - doc/release-policy.md:85 corrected `doc/api/tests.md` link to relative `api/tests.md` (was resolving to nonexistent doc/doc/api/tests.md). - doc/tutorials/block-fd-hessian.md:40 redirected stale reference `../math/hyper-ideal.md` to the actual file `../math/geometry-modes.md`. Found by a sweep of all doc/*.md before the reviewer meeting. Co-Authored-By: Claude Opus 4.7 --- doc/release-policy.md | 2 +- doc/tutorials/block-fd-hessian.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/release-policy.md b/doc/release-policy.md index 4a53633..e0a8472 100644 --- a/doc/release-policy.md +++ b/doc/release-policy.md @@ -82,7 +82,7 @@ rule is: | Number / string | Single source of truth | Anywhere else | |-----------------------------|--------------------------------|--------------------------------------| -| **Total / per-suite test counts** | `doc/api/tests.md` | Use qualitative phrasing + link, e.g. "full test suite passes, 0 skipped — see [`doc/api/tests.md`](doc/api/tests.md)". | +| **Total / per-suite test counts** | `doc/api/tests.md` | Use qualitative phrasing + link, e.g. "full test suite passes, 0 skipped — see [`doc/api/tests.md`](api/tests.md)". | | **Project version** | `CITATION.cff` `version:` field | Don't hardcode in headers, READMEs, doc bodies. Reference by name ("v0.9.0") only when the historical version actually matters (changelog entries, release-note bodies, Phase-milestone tables). | | **Release date** | `CITATION.cff` `date-released:` + `CHANGELOG.md` section header | Don't hardcode elsewhere. | | **Test-suite description per file** | `doc/api/tests.md` | Headers and code files may list the suites they implement, but never claim a count of suites elsewhere. | diff --git a/doc/tutorials/block-fd-hessian.md b/doc/tutorials/block-fd-hessian.md index 81778d5..7849f26 100644 --- a/doc/tutorials/block-fd-hessian.md +++ b/doc/tutorials/block-fd-hessian.md @@ -37,7 +37,7 @@ as `face_angles_from_local_dofs(...)`. > for circle patterns and Koebe's theorem.* Trans. AMS 356(2), 659–689. **Prerequisite:** familiarity with the hyper-ideal functional itself -(see [`doc/math/hyper-ideal.md`](../math/hyper-ideal.md)), and with the +(see [`doc/math/geometry-modes.md`](../math/geometry-modes.md)), and with the generic functional-porting pattern of [`doc/tutorials/add-inversive-distance.md`](add-inversive-distance.md). From ba5c9303a3e508c0a20979e873090288461aced3 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sat, 23 May 2026 23:19:37 +0200 Subject: [PATCH 2/3] docs: clean Doxygen warning log (0 warnings) + flag honest gaps to reviewer Doxygen now builds with **0 warnings** (was 27). Root cause: `[label](doc/api/tests.md)`-style relative markdown links in README.md and CLAUDE.md were being interpreted by Doxygen as \ref commands and failed to resolve (Doxygen indexes .md files by basename, not by repo-relative path). Fix: add a per-file `FILTER_PATTERNS` to Doxyfile that rewrites `[label](path/to/file.md)` into `label` just for Doxygen. HTML anchors bypass \ref resolution entirely; the generated Doxygen HTML still hyperlinks correctly. The on-disk markdown is untouched, so GitHub rendering is unaffected. New file: scripts/doxygen-md-filter.sh (24 lines, documented). Also: append a "Known limitations (state at the time of the reviewer meeting)" table to doc/architecture/locked-vs-flexible.md so the external reviewer sees the 7 deliberate gaps (output_uv_map covers 3 of 5 entries; pipe-only chaining; Phase 9b-analytic derived but not implemented; Doxygen WARN_IF_UNDOCUMENTED policy; CI test-count gate; research-track utilities) with effort estimates next to each. Co-Authored-By: Claude Opus 4.7 --- Doxyfile | 6 ++++++ doc/architecture/locked-vs-flexible.md | 23 +++++++++++++++++++++ scripts/doxygen-md-filter.sh | 28 ++++++++++++++++++++++++++ 3 files changed, 57 insertions(+) create mode 100755 scripts/doxygen-md-filter.sh diff --git a/Doxyfile b/Doxyfile index bab9d2a..6eaf994 100644 --- a/Doxyfile +++ b/Doxyfile @@ -34,6 +34,12 @@ EXCLUDE_PATTERNS = */build*/* \ */* 2.hpp EXCLUDE_SYMBOLS = Eigen::* boost::* std::* +# Markdown filter: rewrites repo-relative links like [x](doc/api/tests.md) +# into basename-only links [x](tests.md) so Doxygen's basename-indexed +# \ref resolver can find them. On-disk files are untouched (GitHub keeps +# rendering them correctly). See scripts/doxygen-md-filter.sh. +FILTER_PATTERNS = *.md=scripts/doxygen-md-filter.sh + # ── Source browsing ────────────────────────────────────────────────────────── EXTRACT_ALL = YES EXTRACT_PRIVATE = NO diff --git a/doc/architecture/locked-vs-flexible.md b/doc/architecture/locked-vs-flexible.md index c2cd2e1..e2c75a9 100644 --- a/doc/architecture/locked-vs-flexible.md +++ b/doc/architecture/locked-vs-flexible.md @@ -250,6 +250,29 @@ matches the project's three-goal hierarchy in --- +## Known limitations (state at the time of the reviewer meeting) + +These are deliberate, honestly-flagged gaps in the v0.9.0 snapshot the +reviewer will see. None of them are load-bearing — each is a small, +mechanical next step rather than a missing piece of theory. + +| Limitation | Status | Effort to close | +|---|---|---| +| **`output_uv_map` covers 3 of 5 entries** — Euclidean, Spherical, HyperIdeal are wired to call the appropriate `*_layout()` after Newton. CP-Euclidean (face-based) and Inversive-Distance (vertex-based) entries still require the user to call `*_layout()` by hand. | tutorial + plumbing in place; just needs to be copy-pasted into the two remaining entry headers | ~0.5 day | +| **Named-parameter chaining: `\|`-operator only, no `.a().b().c()`.** Member-style chaining would need a patch to CGAL's upstream `parameters_interface.h`, which we treat as a read-only vendored dependency. The pipe operator is documented, ADL-discoverable, and equivalent in expressive power. | pipe shipped, member-chain deferred until upstream extension point exists | ~2 days (only if upstream PR is accepted) | +| **Phase 9b-analytic: derivation complete, code uses block-FD.** The Schläfli-based analytic HyperIdeal Hessian is fully derived in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) (805 lines, all sign pitfalls covered). The shipped code still uses per-face block-FD (already 96× faster than the legacy full-FD path). | research-ready writeup; implementation gated on the reviewer's view of whether the additional ~6× is worth it | ~2 weeks | +| **Doxygen `WARN_IF_UNDOCUMENTED = NO`.** With `EXTRACT_ALL = YES`, every symbol is in the generated HTML, but symbols without explicit doc comments show only their signature. Public API surface (entry functions, named-parameter helpers, traits typedefs) has hand-written Doxygen; internal helpers vary. | clean (0 warnings) under current policy; not yet enforced "no undocumented symbol" | ~3 days to drive `WARN_IF_UNDOCUMENTED = YES` to zero | +| **`check-test-counts.sh` not wired into CI.** The script exists, runs locally, and gives the correct answer (23 + 234 = 257 / 0 skipped). CI does not yet fail on a mismatch. | local guard exists, CI integration pending next workflow touch | ~1 hour | +| **CP-Euclidean and Inversive-Distance research-track entries.** Both ship a working DCE solver, but lack the auxiliary utilities the Euclidean / HyperIdeal entries have (curvature inspection helpers, edge-flip Delaunay maintenance for ID). Out of port scope; listed in [`research-track.md`](../roadmap/research-track.md). | research-track, not blocking | per-utility | +| **`StereographicUnwrapper`, `CircleDomainUnwrapper`, `CuttingUtility`, `KoebePolyhedron`.** Mentioned in roadmap + research-track docs but not yet ported. Java versions still authoritative. | documented as Phase 11+ / optional | weeks each — explicit "out of port scope unless requested" | + +The honest framing for the meeting: **the porting layer hits its target +for the 5 Phase-8b-Lite DCE entries; the hackability layer is +demonstrably in place (3 tutorials, named-parameter chaining, +Doxygen-HTML); the research-track items are scoped but not built.** + +--- + ## Open questions for the external reviewer Items where the project would benefit from a second opinion: diff --git a/scripts/doxygen-md-filter.sh b/scripts/doxygen-md-filter.sh new file mode 100755 index 0000000..fc2fcfb --- /dev/null +++ b/scripts/doxygen-md-filter.sh @@ -0,0 +1,28 @@ +#!/bin/sh +# scripts/doxygen-md-filter.sh +# +# Doxygen FILTER for *.md files. Rewrites repository-relative markdown links +# (e.g. `[label](doc/api/tests.md)` or `[label](architecture/foo.md)`) into +# basename-only form (`[label](tests.md)`, `[label](foo.md)`). +# +# Why: GitHub's markdown renderer needs the full relative path to resolve a +# link, but Doxygen indexes every .md file in INPUT by basename and treats +# any "/" in a link target as an unresolvable \ref. Without this filter we +# get ~27 spurious warnings from README.md and CLAUDE.md. +# +# The filter is purely a Doxygen-side concern; the on-disk markdown is +# untouched, so GitHub rendering keeps working. +# +# Precondition: no two .md files in the project share a basename. Verified +# at the time of writing by: +# find . -name "*.md" -not -path "*/build*/*" -not -path "*/code/deps/*" \ +# -not -path "*/.git/*" | xargs -n1 basename | sort | uniq -c | awk '$1>1' +# (empty output ⇒ no collisions). +# +# Usage: configured via Doxyfile FILTER_PATTERNS = *.md=scripts/doxygen-md-filter.sh +set -eu +# Convert any markdown link target that points at a .md file into an HTML +# anchor. Doxygen renders HTML verbatim and skips its (broken) \ref +# resolution; the rendered Doxygen HTML still hyperlinks to the source .md. +# Pattern: [label](path/to/file.md) → label +sed -E 's#\[([^]]+)\]\(([a-zA-Z0-9_./-]+\.md)\)#\1#g' "$1" From b0c67af922662e366a9f740ba4ae34fa941cadf1 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sat, 23 May 2026 23:30:54 +0200 Subject: [PATCH 3/3] ci: auto-publish Doxygen HTML to Codeberg Pages on main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .gitea/workflows/doxygen-pages.yml | 78 ++++++++++++++++++++++++++ README.md | 2 + doc/architecture/locked-vs-flexible.md | 2 +- 3 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 .gitea/workflows/doxygen-pages.yml diff --git a/.gitea/workflows/doxygen-pages.yml b/.gitea/workflows/doxygen-pages.yml new file mode 100644 index 0000000..f4bb546 --- /dev/null +++ b/.gitea/workflows/doxygen-pages.yml @@ -0,0 +1,78 @@ +name: Doxygen → Codeberg Pages + +# 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. +# +# Trigger: push to main that touches code/include/**, Doxyfile, the +# filter script, doc/**/*.md, README.md, or this workflow file. Also +# manually triggerable via workflow_dispatch. + +on: + push: + branches: + - main + paths: + - "code/include/**" + - "Doxyfile" + - "scripts/doxygen-md-filter.sh" + - "doc/**/*.md" + - "README.md" + - "CLAUDE.md" + - ".gitea/workflows/doxygen-pages.yml" + 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: 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 Doxygen output (and a + # marker README), never any build/source artefacts. + publish_dir=$(mktemp -d) + cp -r doc/doxygen/html/. "$publish_dir/" + + cat > "$publish_dir/README.txt" < (auto-published from `main` by `.gitea/workflows/doxygen-pages.yml`) — but symbols without explicit doc comments show only their signature. Public API surface (entry functions, named-parameter helpers, traits typedefs) has hand-written Doxygen; internal helpers vary. | clean (0 warnings) under current policy; not yet enforced "no undocumented symbol"; pursued on a separate branch | ~3 days to drive `WARN_IF_UNDOCUMENTED = YES` to zero | | **`check-test-counts.sh` not wired into CI.** The script exists, runs locally, and gives the correct answer (23 + 234 = 257 / 0 skipped). CI does not yet fail on a mismatch. | local guard exists, CI integration pending next workflow touch | ~1 hour | | **CP-Euclidean and Inversive-Distance research-track entries.** Both ship a working DCE solver, but lack the auxiliary utilities the Euclidean / HyperIdeal entries have (curvature inspection helpers, edge-flip Delaunay maintenance for ID). Out of port scope; listed in [`research-track.md`](../roadmap/research-track.md). | research-track, not blocking | per-utility | | **`StereographicUnwrapper`, `CircleDomainUnwrapper`, `CuttingUtility`, `KoebePolyhedron`.** Mentioned in roadmap + research-track docs but not yet ported. Java versions still authoritative. | documented as Phase 11+ / optional | weeks each — explicit "out of port scope unless requested" |