Merge pull request 'Docs + CI: link fixes, 0-warning Doxygen, Codeberg Pages auto-publish' (#16) from ci/doxygen-pages-autopublish into main

.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" <<EOF
+          conformallab++ — Doxygen HTML API documentation.
+          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
+          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

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

README.md

@@ -3,6 +3,7 @@
 [![CI](https://git.eulernest.eu/conformallab/ConformalLabpp/actions/workflows/cpp-tests.yml/badge.svg)](https://git.eulernest.eu/conformallab/ConformalLabpp/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![DOI](https://img.shields.io/badge/doi-Sechelmann%202016-blue)](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f)
+[![API docs](https://img.shields.io/badge/API%20docs-Doxygen-orange)](https://tmoussa.codeberg.page/ConformalLabpp/)
 
 C++17 reimplementation of [ConformalLab](https://github.com/varylab/conformallab) —
 Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin).
@@ -81,6 +82,7 @@ Layout2D layout = euclidean_layout(mesh, res.x, maps);
 
 | | |
 |---|---|
+| **API reference (Doxygen HTML)** — every public class, function and named-parameter helper | https://tmoussa.codeberg.page/ConformalLabpp/ |
 | **Getting started** — build modes, single-test invocation, CLI, Docker | [doc/getting-started.md](doc/getting-started.md) |
 | **Pipeline API** — all three geometries, holonomy, serialisation | [doc/api/pipeline.md](doc/api/pipeline.md) |
 | **Public headers** — all public headers with descriptions | [doc/api/headers.md](doc/api/headers.md) |

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 — live at <https://tmoussa.codeberg.page/ConformalLabpp/> (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" |
+
+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:

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. |

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).
 

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)  →  <a href="path/to/file.md">label</a>
+sed -E 's#\[([^]]+)\]\(([a-zA-Z0-9_./-]+\.md)\)#<a href="\2">\1</a>#g' "$1"