ENH: Add a warnings-only Doxygen CI check#6434
Merged
hjmjohnson merged 9 commits intoJun 11, 2026
Merged
Conversation
github-actions
Bot
added
type:Infrastructure
hjmjohnson
force-pushed
the
add-doxygen-warnings-gha
branch
from
605a92d to
3fc08bd
Compare
Member
Author
|
@greptileai review this draft before I make it official |
This comment was marked as resolved.
This comment was marked as resolved.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
hjmjohnson
force-pushed
the
add-doxygen-warnings-gha
branch
3 times, most recently
from
cce2ff9 to
d535a3d
Compare
The pixi doxygen-ci task configures with ITK_BUILD_DOCUMENTATION=ON, regenerates Examples.dox, and runs Doxygen with WARN_AS_ERROR set and HTML/LaTeX/dot generation disabled (under two minutes end to end). The workflow gates pull requests, complementing the post-merge Linux-Ubuntu-GCC-Doxygen nightly that tracks these warnings today.
Doxygen shells out to perl and bibtex for \cite resolution and to dot for explicit \dot graphs; the bare runner lacked all three, turning every citation into a 'no associated number' warning.
HAVE_DOT=NO made every module dependency page warn 'ignoring \dot command'; disable only the implicit graph classes instead.
Remote-module fetches and ExternalData downloads are irrelevant to a documentation-only configure; ITK_FORBID_DOWNLOADS keeps the runner hermetic and the warning scan free of cloned checkouts.
The custom command producing Examples.dox had no consumer, so the Documentation target ran Doxygen against a missing or stale examples page unless the file was generated by hand.
Single-sources the warnings-as-errors Doxyfile at configure time so CI, the nightly dashboard, and local builds share one override set: no output formats, implicit graphs disabled (explicit \dot still renders), WARN_AS_ERROR=FAIL_ON_WARNINGS, and a fixed warning log at <build>/doxygen-warnings.log. The HTML logo copy is skipped when no HTML is generated.
The doxygen-ci task now builds the Documentation target; the override set lives in the CMake layer instead of an appended Doxyfile copy. Dropping the configure task's outputs declaration makes pixi rerun the configure after pyproject or CMake edits rather than reusing a stale Doxyfile.
perl and graphviz resolve everywhere; bibtex must come from a system TeX distribution on macOS and Windows since conda-forge texlive-core is linux-only.
Dropping the pull_request paths filter lets the check become a required status without stranding filtered PRs. The build-doxygen cache trims the configure cost, and failures now also upload the effective Doxyfile alongside the warning log.
hjmjohnson
force-pushed
the
add-doxygen-warnings-gha
branch
from
d535a3d to
593fab6
Compare
dzenanz
approved these changes
Jun 11, 2026
hjmjohnson
merged commit e59c2b4
into
InsightSoftwareConsortium:main
14 of 17 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a per-PR
doxygen-warningsGitHub Actions check built on a newITK_DOXYGEN_WARNINGS_ONLYCMake mode:pixi run doxygen-ciconfigures with the mode on and builds the existingDocumentationtarget, which now fails on any Doxygen warning. Closes the gap where Doxygen regressions are only caught by the post-mergeLinux-Ubuntu-GCC-Doxygennightly.Design
ITK_DOXYGEN_WARNINGS_ONLY(CMake, advanced): disables all output formats and implicit graph classes (explicit\dotstill renders), setsWARN_AS_ERROR=FAIL_ON_WARNINGSand a fixed warning log at<build>/doxygen-warnings.log. Single-sourced so the nightly dashboard and local builds can reuse the same mode.Examples.doxcustom command had no consumer — theDocumentationtarget never generated it. Now wired via anITKDoxygenExamplesDoxtarget.doxygenfeature/environment (doxygen, perl, bibtex via linux-onlytexlive-core, graphviz) and two tasks; manual runs on macOS/Windows resolve perl+graphviz from conda-forge and need bibtex from a system TeX distribution.build-doxygen, uploads the warning log and effective Doxyfile on failure.Measurements and validation
pixi.lockregenerated with pixi 0.70.2.