DOC: Update Doxygen XML for ITK 5.3.0

[thewtex]

Note: This is intentionally not updated to the ITK source code version so we can bump the source version separately.

[thewtex]

I am not sure why we are seeing these warnings:

https://open.cdash.org/viewBuildError.php?type=1&buildid=8385181

:confused:

[jhlegarreta]

Was the word "intentially" intentionally used in the commit message?

[thewtex]

Was the word "intentially" intentionally used in the commit message?

No :smile: :laughing:

[jhlegarreta]

I am not sure why we are seeing these warnings: https://open.cdash.org/viewBuildError.php?type=1&buildid=8385181

I do not know either Matt. Looks like the latest build points at some additional warnings: https://open.cdash.org/viewBuildError.php?type=1&buildid=8386005 https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/actions/runs/3870763866/jobs/6597968633#step:9:12602

• It looks as if finding the same breathlinks would bother Sphinx: e.g. https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/blame/468ee04f79c5386393db1aa6929200f2eeb6126c/src/Core/Common/CreateVectorImage/Documentation.rst#L34 and https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/blame/468ee04f79c5386393db1aa6929200f2eeb6126c/src/Core/Common/CastVectorImageToAnotherType/Documentation.rst#L34

• It looks like the class documentation block is not correctly processed by Doxygen for some classes e.g. https://github.com/InsightSoftwareConsortium/ITK/blob/87a66198e11920eeb04db1d6125a37e83cf4ebf6/Modules/Numerics/Statistics/include/itkSampleToHistogramFilter.h

  Cannot be found under the ITK namespace in: https://itk.org/Doxygen53/html/annotated.html or under the Statistics namespace: https://itk.org/Doxygen53/html/namespaceitk_1_1Statistics.html

[tbirdso]

Previously noticed these tag file warnings/errors last year in https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/issues/362, the workaround at that time was to pin to v5.2.0 tag files which we obviously no longer want to do. I'm not sure what causes these issues. It sounds like the warnings may have stemmed from a doxygen version bump, the dates given in that issue discussion may aid in investigation.

[jhlegarreta]

• Interestingly one of the classes at issue, SampleToHistogramFilter, was present in the ITK 5.1/5.2 Doxygen: https://itk.org/Doxygen51/html/classitk_1_1Statistics_1_1SampleToHistogramFilter.html https://itk.org/Doxygen52/html/classitk_1_1Statistics_1_1SampleToHistogramFilter.html

  https://itk.org/Doxygen52/html/namespaceitk_1_1Statistics.html https://itk.org/Doxygen51/html/namespaceitk_1_1Statistics.html vs https://itk.org/Doxygen53/html/namespaceitk_1_1Statistics.html

  A blame shows 5 commits since ITK 5.1. The one that I'd say may be related is the last one, which I contributed myself: https://github.com/InsightSoftwareConsortium/ITK/commits/87a66198e11920eeb04db1d6125a37e83cf4ebf6/Modules/Numerics/Statistics/include/itkSampleToHistogramFilter.h

  Other classes that went through the same change are present in Doxygen, though: https://itk.org/Doxygen53/html/classitk_1_1VTKImageExport.html

• A couple of 2 other points: https://raw.githubusercontent.com/InsightSoftwareConsortium/ITKSphinxExamples/5018e60c875c44ca6bdf6198b798b0010ef8e3f7/src/Numerics/Statistics/CreateHistogramFromListOfMeasurements/Documentation.rst https://raw.githubusercontent.com/InsightSoftwareConsortium/ITKSphinxExamples/5018e60c875c44ca6bdf6198b798b0010ef8e3f7/src/Core/Common/CastVectorImageToAnotherType/Documentation.rst

  • Show a histogram class in the index that is surely not found (will submit a patch set)
  • Show a pair: cast; VectorImage in the index that I am not sure was meant that way (the code shows the use of itk::CastImageFilter) (will submit a patch set)

[jhlegarreta]

Show a histogram class in the index that is surely not found (will submit a patch set) Show a pair: cast; VectorImage in the index that I am not sure was meant that way (the code shows the use of itk::CastImageFilter) (will submit a patch set)

PR #412. One thing that I wonder is why the second one has a single then a pair entry with the latter containing an element that is already in single. I did not find the behavior documented in Sphinx. @thewtex @tbirdso ?

[jhlegarreta]

PR https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/pull/412. One thing that I wonder is why the second one has a single then a pair entry with the latter containing an element that is already in single. I did not find the behavior documented in Sphinx. @thewtex @tbirdso ?

Nevermind. I figured out what the purpose and effect is.

[tbirdso]

PR #412. One thing that I wonder is why the second one has a single then a pair entry with the latter containing an element that is already in single. I did not find the behavior documented in Sphinx. @thewtex @tbirdso ?

Nevermind. I figured out what the purpose and effect is.

Hi @jhlegarreta , I am not clear on what these tags do, was there documentation that helped you or could you briefly summarize what you found?

[jhlegarreta]

Hi @jhlegarreta , I am not clear on what these tags do, was there documentation that helped you or could you briefly summarize what you found?

They serve to create the index: https://examples.itk.org/genindex.html

For the case at issue, it single creates the VectorImage entry we see in V (hover on the class name); the pair creates the entry as a composite entry by subindexing both as cast/VectorImage and VectorImage/cast.

[thewtex]

It seems we should rebase after @jhlegarreta 's related patches are in, check to see if the warnings actually cause issues in the generated documentation, ignore them if not, and keep https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/issues/362 open to track the issue.

[thewtex]

Rebasing on master

[jhlegarreta]

It's a CMake warning that is making the ubuntu-22.04 documentation check fail: https://open.cdash.org/build/8867148/configure

I thought we had fixed this one.

And some other Doxygen warnings: https://open.cdash.org/viewBuildError.php?type=1&buildid=8867148

[jhlegarreta]

It's a CMake warning that is making the ubuntu-22.04 documentation check fail: https://open.cdash.org/build/8867148/configure

I thought we had fixed this one.

Does not look like we fixed properly in other places either: InsightSoftwareConsortium/ITK#3846

And some other Doxygen warnings: https://open.cdash.org/viewBuildError.php?type=1&buildid=8867148

Not sure what the problem is with itk::AddImageFilter and itk::SampleToHistogramFilter:

• The first one has two entries in the Doxygen class list: https://itk.org/Doxygen/html/classes.html or https://itk.org/Doxygen/html/annotated.html. It's also not in the itk namespace.
• The second one is not present in the Doxygen class list.

Maybe the warnings in the GHA builds https://github.com/InsightSoftwareConsortium/ITKDoxygen/actions/runs/5720889621/job/15501589831 and/or in the dashboard https://open.cdash.org/viewBuildError.php?type=1&buildid=8879198

need attention. A quick look did not result in meaningful insight about the errors.

[jhlegarreta]

Some further comments:

• It looks as if Doxygen was trying to consider AddImageFilter as the name of a group, enum or namespace in here: https://itk.org/Doxygen/html/annotated.html. Maybe Doxygen is trying to create a group for the Ternary, Nary, Weighted variants?
• The inheritance and collaboration diagram generation is also failing for AddImageFilter; but not for the Ternary, Nary, Weighted variants.
• PowImagFilter has the same issues.
• The class is being linked correctly, pointing to the ITK 5.3.0 version, from the ITK SWG: https://github.com/InsightSoftwareConsortium/ITK/blob/c3ee320bf82cc3ce2c916240d922e2ace2335f9f/Examples/Filtering/LaplacianRecursiveGaussianImageFilter1.cxx#L281 https://itk.org/ItkSoftwareGuide.pdf https://itk.org/Doxygen/html/classitk_1_1AddImageFilter.html However, when navigating to the class list, the same issues as in the nightly version are present: https://itk.org/Doxygen53/html/annotated.html
• Maybe there is some tab or some other wanted, at first sight invisible character?

I've already run out of ideas Matt.

[thewtex]

@jhlegarreta thanks for diving in here!

The inheritance and collaboration diagram generation is also failing for AddImageFilter; but not for the Ternary, Nary, Weighted variants. PowImagFilter has the same issues.

Based on this evaluation / observation, I noticed an difference in AddImageFilter, PowImageFilter vs the Nary, Ternary, Weighted AddImageFilters that is removed here:

https://github.com/InsightSoftwareConsortium/ITK/pull/4208

Crossing fingers that addresses these issues :crossed_fingers: .