From b0c67af922662e366a9f740ba4ae34fa941cadf1 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Sat, 23 May 2026 23:30:54 +0200 Subject: [PATCH] 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" |