Skip to content

Doxygen tag file missing from releases since v5.3.0; downstream class links broken #6439

@hjmjohnson

Description

@hjmjohnson

The InsightDoxygenDocTag-<version>.gz release artifact stopped shipping after v5.3.0, even though Documentation/Maintenance/Release.md still requires it. Downstream documentation builds (ITKSphinxExamples) that resolve itk:: class references through the tag file are pinned to the stale 5.3.0 copy, which predates current class compounds and produces broken/missing class links.

Root cause

When nightly Doxygen generation moved to the ITKDoxygen GHA repository (Discourse #4790), its packaging only shipped the Html and Xml tarballs. Doxygen generates InsightDoxygen.tag on every run (Utilities/Doxygen/DoxygenConfig.cmake sets GENERATE_TAGFILE), but run.sh never copies it out of the container — so the "download from the latest ITKDoxygen Release and rename" release flow silently lost the asset. No issue, PR, or Discourse thread records a decision to drop it; it is an unnoticed omission.

Two secondary coverage gaps were found while diagnosing this in ITKSphinxExamples (InsightSoftwareConsortium/ITKSphinxExamples#458):

  1. The v5.3.0-era Doxygen run produced no class compounds for itk::AddImageFilter and itk::Statistics::SampleToHistogramFilter (the only published XML/tag with them is now v6.0b01).
  2. Current ITKDoxygen artifacts lack itk::ImageToVTKImageFilter, itk::VTKImageToImageFilter, and itk::OpenCVImageBridge, because the docker build does not enable Module_ITKVtkGlue / Module_ITKVideoBridgeOpenCV (no VTK/OpenCV in the image); the 5.3-era build covered them.

Proposed plan

  1. ITKDoxygen (authoritative artifact set)ENH: Publish the Doxygen tag file; document VtkGlue and OpenCV classes ITKDoxygen#43: publish the tag as InsightDoxygenDocTag-latest.gz next to Html/Xml, and add VTK/OpenCV to the image so the bridge-module classes return. One Doxygen run then produces a consistent html+xml+tag set.
  2. ITK release tagsENH: Publish the Doxygen tag file on release tags #6438: the warnings-only Doxygen CI (ENH: Add a warnings-only Doxygen CI check #6434) already generates the tag as its sole output; v* tag pushes now upload InsightDoxygenDocTag-<version>.gz to the release, restoring Release.md compliance with no manual steps. Its module set is aligned with the ITKDoxygen nightly.
  3. ITKSphinxExamplesCOMP: Track ITKDoxygen latest artifacts; revert doxygen warning suppression ITKSphinxExamples#458: after (1) lands and a nightly completes, point the XML/HTML/tag downloads at the ITKDoxygen latest release (the examples build ITK main, so tracking latest is more correct than pinning immutable release assets) and remove the temporary missing-class warning exception.

Acceptance

  • InsightDoxygenDocTag-* present in the ITKDoxygen latest release and in the next ITK release's assets.
  • ITKSphinxExamples documentation build green with zero doxygen-lookup warning exceptions.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions