DOC: inconsistent dependencies for documentation build

[albert-github]

Handling the addition and removal of example files for the file Examples.dox

fixes #6545

PR Checklist

• No API changes were made (or the changes have been approved)
• No major design changes were made (or the changes have been approved)

[greptile-apps]

Greptile Summary

This PR updates the documentation build dependencies for generated example documentation. The main changes are:

• Collect example source files with GLOB_RECURSE CONFIGURE_DEPENDS.
• Regenerate Examples.dox when example files are added, removed, or changed.
• Use the generated Examples.dox path in the Doxygen input list.

Confidence Score: 4/5

The PR is close, but the documentation build rule needs a path fix before merging.

One contained build-rule bug was found in the changed CMake logic. The intended dependency tracking change is localized to documentation generation.

Utilities/Doxygen/CMakeLists.txt

T-Rex Logs

What T-Rex did

• Attempted to configure and build the CMake harness, but cmake and ninja were unavailable, so the run remained blocked.
• Validated the environment shows CMake and Doxygen are unavailable while Python is available.
• The smoke harness ran and reported EXIT_CODE: 0 with all assertions passing.
• Dox example outputs show TrexValidationRemovedExample.java only in before outputs, while TrexValidationAddedExample.py appears in both before and after outputs.
• Stopped before creating a reproduction harness because CMake remained unavailable.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
Utilities/Doxygen/CMakeLists.txt	Adds dependency tracking for example source files when generating Examples.dox, but the custom command declares a different output path than the script writes.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Build as CMake build
participant Glob as EXAMPLES_LIST glob
participant Target as ITKDoxygenExamplesDox
participant Script as GenerateExamplesDox.cmake
participant Out as Documentation/Doxygen/Examples.dox
Build->>Glob: "collect Examples/*.cxx, *.py, *.java"
Glob-->>Target: file dependencies
Target->>Script: "run with OUTPUT_FILE=${ITK_EXAMPLES}"
Script->>Out: generate Examples.dox
Target-->>Build: "documentation input uses ${ITK_EXAMPLES}"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Build as CMake build
participant Glob as EXAMPLES_LIST glob
participant Target as ITKDoxygenExamplesDox
participant Script as GenerateExamplesDox.cmake
participant Out as Documentation/Doxygen/Examples.dox
Build->>Glob: "collect Examples/*.cxx, *.py, *.java"
Glob-->>Target: file dependencies
Target->>Script: "run with OUTPUT_FILE=${ITK_EXAMPLES}"
Script->>Out: generate Examples.dox
Target-->>Build: "documentation input uses ${ITK_EXAMPLES}"

Loading

_{Reviews (1): Last reviewed commit: "DOC: inconsistent dependencies for docum..." | Re-trigger Greptile}

[greptile-apps]

Match generated output
OUTPUT Examples.dox and the target dependency are relative to this CMake directory’s binary tree, but the script writes to ${ITK_EXAMPLES} under Documentation/Doxygen. With Ninja/Make, the declared output is never produced, so the custom command remains out of date or fails after generation even though the intended file exists.

[hjmjohnson]

@albert-github Can you please address this greptile concern?

[albert-github]

I will look into it, but it will take a bit over a week before I have time to really look into it (and I don't have ninja).

[hjmjohnson]

@albert-github

Greptile is right, and I confirmed with a minimal Ninja reproduction that this fails on a fresh build tree. Two problems:

1. A relative OUTPUT Examples.dox resolves to ${ITK_BINARY_DIR}/Utilities/Doxygen/Examples.dox (this directory's binary dir), while the script writes to ${ITK_EXAMPLES} under Documentation/Doxygen — so the declared output is never produced.
2. Ninja does not create WORKING_DIRECTORY, so cd .../Documentation/Doxygen fails before the script even runs. Since GenerateExamplesDox.cmake uses only absolute paths, the WORKING_DIRECTORY can be dropped entirely.

Suggested replacement (verified to build and be a no-op on rebuild with Ninja):

add_custom_command(
  OUTPUT
    ${ITK_EXAMPLES}
  COMMAND
    ${CMAKE_COMMAND} -D "PROJECT_SOURCE_DIR:PATH=${ITK_SOURCE_DIR}" -D
    "OUTPUT_FILE:PATH=${ITK_EXAMPLES}" -P
    "${ITK_SOURCE_DIR}/Utilities/Doxygen/GenerateExamplesDox.cmake"
  DEPENDS
    ${EXAMPLES_LIST}
    "${ITK_SOURCE_DIR}/Utilities/Doxygen/GenerateExamplesDox.cmake"
)
add_custom_target(ITKDoxygenExamplesDox ALL DEPENDS ${ITK_EXAMPLES})

The set_source_files_properties(... GENERATED 1) block can also be removed — add_custom_command outputs are automatically marked GENERATED — and please delete the commented-out #WORKING_DIRECTORY line rather than keeping it.