Docs + CI: link fixes, 0-warning Doxygen, Codeberg Pages auto-publish #16

user2595 · 2026-05-23T21:31:47Z

user2595 commented

2026-05-23 21:31:47 +00:00

Combines three sequential commits already on the branch into a single PR for review:

docs: fix 2 broken internal links (release-policy.md, block-fd-hessian.md)
docs: clean Doxygen warning log (0 warnings) + flag honest gaps to reviewer
ci: auto-publish Doxygen HTML to Codeberg Pages on main

After merge, https://tmoussa.codeberg.page/ConformalLabpp/ updates automatically on every push to main that touches public headers, Doxyfile, the filter, doc/**/*.md, README.md, or the workflow itself.

Combines three sequential commits already on the branch into a single PR for review: 1. `docs: fix 2 broken internal links` (release-policy.md, block-fd-hessian.md) 2. `docs: clean Doxygen warning log (0 warnings) + flag honest gaps to reviewer` 3. `ci: auto-publish Doxygen HTML to Codeberg Pages on main` After merge, https://tmoussa.codeberg.page/ConformalLabpp/ updates automatically on every push to main that touches public headers, Doxyfile, the filter, doc/**/*.md, README.md, or the workflow itself.

user2595 added 3 commits 2026-05-23 21:31:48 +00:00

docs: fix 2 broken internal links 0b1bf07232

- 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 <noreply@anthropic.com>

docs: clean Doxygen warning log (0 warnings) + flag honest gaps to reviewer ba5c9303a3

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 `<a href="path/to/file.md">label</a>`
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 <noreply@anthropic.com>

ci: auto-publish Doxygen HTML to Codeberg Pages on main

C++ Tests / test-fast (pull_request) Successful in 2m50s

Details

API Docs / doc-build (pull_request) Successful in 37s

Details

C++ Tests / test-cgal (pull_request) Failing after 11m51s

Details

b0c67af922

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>

user2595 merged commit 8869ead3c9 into main

2026-05-23 21:32:22 +00:00

user2595 referenced this issue from a commit

2026-05-23 21:32:24 +00:00

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: conformallab/ConformalLabpp#16