Failure to find classes in `ITKDoxygenTAG/InsightDoxygen.tag`

[tbirdso]

CI is failing with 6 warnings from missing TAG file definitions:

CDash results

2022-05-16T17:37:04.4831048Z /home/runner/work/bld/ITKEx-build/src/Filtering/ImageIntensity/AddConstantToEveryPixel/Documentation.rst:41: WARNING: doxygenclass: Cannot find class "itk::AddImageFilter" in doxygen xml output for project "ITK" from directory: /home/runner/work/bld/ITKEx-build/ITKDoxygenXML
2022-05-16T17:37:04.4832379Z /home/runner/work/bld/ITKEx-build/src/Filtering/ImageIntensity/AddConstantToEveryPixel/Documentation.rst:41: WARNING: Could not find match for `itk::AddImageFilter` in `/home/runner/work/bld/ITKEx-build/ITKDoxygenTAG/InsightDoxygen.tag` tag file. Error reported was Could not find a match
2022-05-16T17:37:04.4833848Z /home/runner/work/bld/ITKEx-build/src/Filtering/ImageIntensity/AddTwoImages/Documentation.rst:34: WARNING: doxygenclass: Cannot find class "itk::AddImageFilter" in doxygen xml output for project "ITK" from directory: /home/runner/work/bld/ITKEx-build/ITKDoxygenXML
2022-05-16T17:37:04.4875018Z /home/runner/work/bld/ITKEx-build/src/Filtering/ImageIntensity/AddTwoImages/Documentation.rst:34: WARNING: Could not find match for `itk::AddImageFilter` in `/home/runner/work/bld/ITKEx-build/ITKDoxygenTAG/InsightDoxygen.tag` tag file. Error reported was Could not find a match
2022-05-16T17:37:04.5222485Z /home/runner/work/bld/ITKEx-build/src/Numerics/Statistics/CreateHistogramFromListOfMeasurements/Documentation.rst:45: WARNING: doxygenclass: Cannot find class "itk::Statistics::SampleToHistogramFilter" in doxygen xml output for project "ITK" from directory: /home/runner/work/bld/ITKEx-build/ITKDoxygenXML
2022-05-16T17:37:04.5251169Z /home/runner/work/bld/ITKEx-build/src/Numerics/Statistics/CreateHistogramFromListOfMeasurements/Documentation.rst:45: WARNING: Could not find match for `itk::Statistics::SampleToHistogramFilter` in `/home/runner/work/bld/ITKEx-build/ITKDoxygenTAG/InsightDoxygen.tag` tag file. Error reported was Could not find a match

CI for e49dee5 passed when first run on May 9th and then failed when re-run on May 16th.

https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/blob/master/CMake/DownloadDoxygenTAG.cmake shows that the DoxygenTAG file is located at https://itk.org/files/NightlyDoxygen/InsightDoxygenDocTag.gz. Downloading, decompressing, and inspecting this file shows that it does include definitions for AddImageFilter and SampleToHistogramFilter.

[tbirdso]

@thewtex Could you please weigh in if you have time? Is it possible that the TAG file was changed within the past week, and if so do you maybe have access to the relevant server directory to check timestamps?

Any CI failure prevents docs from being published and updated automatically.

[thewtex]

Yes, the tag has content has been updated last week -- now the results from the nightly Doxygen build are being uploaded.

[tbirdso]

Okay, good to know. I wonder if we need to pin to a stable, previous version rather than always grabbing the nightly build?

itk::AddImageFilter was last updated in 2020 and itk::Statistics::SampleToHistogramFilter was last updated in 2021, so it less likely that the error is directly related to changes there. However there are visible differences between tag files when comparing the most recent nightly tag (5/16/22) to a previous version (3/11/22). Have tag generation procedures changed?

I noticed that an itk:: is missing in the updated file only, perhaps the AddImageFilter warning results from a namespace issue? This does not account for the SampleToHistogramFilter warning.

...
  <compound kind="group">
    <name>ITKImageIntensity</name>
    <title>Module ITKImageIntensity</title>
    <filename>group__ITKImageIntensity.html</filename>
    <subgroup>FourierTransform</subgroup>
    <class kind="class">itk::Functor::Abs</class>
    <class kind="class">itk::AbsImageFilter</class>
    <class kind="class">itk::Functor::AccessorFunctor</class>
    <class kind="class">itk::Functor::Acos</class>
    <class kind="class">itk::AcosImageFilter</class>
    <class kind="class">itk::AdaptImageFilter</class>
    <class kind="class">itk::Functor::Add1</class>
    <class kind="class">itk::Functor::Add2</class>
    <class kind="class">itk::Functor::Add3</class>
    <class kind="class">AddImageFilter</class>             <<<< missing itk::
    <class kind="class">itk::Functor::AND</class>
    <class kind="class">itk::AndImageFilter</class>
...

[thewtex]

@tbirdso yes, it is a good idea to fix to a version, and update explicitly.

Perhaps a Doxygen version bump is causing these issues.

[tbirdso]

Having trouble reproducing via a clean superbuild on Ubuntu 18.04 with Ninja. The ITK tag file matches the nightly version that docs CI should be using?

[thewtex]

The tag file linked to on ITK's Doxygen is generated nightly with the nighly master version of ITK. If we are building against nightly master ITK in Examples CI (was true before, not sure about the current status), then this would make sense to have all the updated definitions of ITK classes. However, it is better to use a fixed version, #365, with older definitions, if tag parsing etc. need to be updated to make the build pass.

[tbirdso]

@thewtex Docs CI builds against the default ITK commit tag set in the ITKSphinxExamples superbuild configuration, which appears to be e801e637634d1cdf050b358299fd7b3771418f2e. I agree that ideally it would be best to use the same tag and ITK doxygen version as a mismatch could lead to issues, which may be a cause of what we're seeing here. Since docs seem to build adequately when reverting to v5.2.0 Doxygen archives, let's stick with that for the time being but leave this issue open for investigation.

EDIT: Reference superbuild ITK tag at https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/blob/master/Superbuild/External-ITK.cmake#L5

EDIT2: ITK commit is recent at InsightSoftwareConsortium/ITK@e801e63, well past ITK v5.2.0

[jhlegarreta]

Cross-referencing InsightSoftwareConsortium/ITK#3655.