DOC: Update Doxygen XML for ITK 5.3.0 #411

thewtex · 2023-01-08T23:05:58Z

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

jhlegarreta

Typo in commit message: intentially -> intentionally ?

CMake/ITKDoxygen.cmake

thewtex · 2023-01-09T01:39:45Z

I am not sure why we are seeing these warnings:

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

😕

jhlegarreta · 2023-01-09T01:49:16Z

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

thewtex · 2023-01-09T04:27:49Z

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

No 😄 😆

jhlegarreta · 2023-01-09T13:17:01Z

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 · 2023-01-09T13:35:19Z

Previously noticed these tag file warnings/errors last year in #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 · 2023-01-10T02:16:57Z

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 · 2023-01-10T02:29:23Z

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 · 2023-01-12T01:29:09Z

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.

tbirdso · 2023-01-12T01:36:31Z

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 · 2023-01-12T01:43:41Z

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 · 2023-01-12T14:08:27Z

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 #362 open to track the issue.

thewtex · 2023-07-24T16:57:19Z

Rebasing on master

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

jhlegarreta · 2023-07-27T01:40:39Z

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 · 2023-08-01T22:54:49Z

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 · 2023-08-02T18:20:35Z

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.

…ageFilter Hopefully this will help with the Doxygen XML issues discussed at: InsightSoftwareConsortium/ITKSphinxExamples#411.

thewtex · 2023-09-07T02:39:20Z

@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:

InsightSoftwareConsortium/ITK#4208

Crossing fingers that addresses these issues 🤞 .

…ageFilter Hopefully this will help with the Doxygen XML issues discussed at: InsightSoftwareConsortium/ITKSphinxExamples#411.

thewtex requested review from tbirdso and jhlegarreta January 8, 2023 23:06

github-actions bot added type:Documentation Documentation improvement or change type:Infrastructure Infrastructure/ecosystem related changes, such as CMake or buildbots labels Jan 8, 2023

jhlegarreta reviewed Jan 8, 2023

View reviewed changes

CMake/ITKDoxygen.cmake Show resolved Hide resolved

thewtex force-pushed the doxygen-5.3.0 branch from 81848e9 to 06ea3ff Compare January 9, 2023 01:39

thewtex force-pushed the doxygen-5.3.0 branch from 06ea3ff to ffeaa4c Compare January 9, 2023 04:27

dzenanz approved these changes Jan 9, 2023

View reviewed changes

thewtex force-pushed the doxygen-5.3.0 branch from ffeaa4c to c7cbe0c Compare July 24, 2023 16:57

thewtex added 2 commits July 26, 2023 17:09

STYLE: Remove extra spaces in CMake/Doxygen*

1b2d2c0

DOC: Update Doxygen XML for ITK 5.3.0

40a8a65

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

thewtex force-pushed the doxygen-5.3.0 branch from c7cbe0c to 40a8a65 Compare July 26, 2023 21:09

thewtex mentioned this pull request Sep 7, 2023

STYLE: Separate \ingroup for MultiThreaded with AddImageFilter, PowImageFilter InsightSoftwareConsortium/ITK#4208

Merged

thewtex added a commit to thewtex/ITK that referenced this pull request Sep 7, 2023

STYLE: Separate \ingroup for MultiThreaded with AddImageFilter, PowIm…

7c7c241

…ageFilter Hopefully this will help with the Doxygen XML issues discussed at: InsightSoftwareConsortium/ITKSphinxExamples#411.

hjmjohnson merged commit 94e4144 into InsightSoftwareConsortium:master Nov 25, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Update Doxygen XML for ITK 5.3.0 #411

DOC: Update Doxygen XML for ITK 5.3.0 #411

thewtex commented Jan 8, 2023 •

edited

Loading

jhlegarreta left a comment •

edited

Loading

thewtex commented Jan 9, 2023

jhlegarreta commented Jan 9, 2023 •

edited

Loading

thewtex commented Jan 9, 2023

jhlegarreta commented Jan 9, 2023 •

edited

Loading

tbirdso commented Jan 9, 2023

jhlegarreta commented Jan 10, 2023

jhlegarreta commented Jan 10, 2023 •

edited

Loading

jhlegarreta commented Jan 12, 2023

tbirdso commented Jan 12, 2023

jhlegarreta commented Jan 12, 2023 •

edited

Loading

thewtex commented Jan 12, 2023

thewtex commented Jul 24, 2023

jhlegarreta commented Jul 27, 2023 •

edited

Loading

jhlegarreta commented Aug 1, 2023

jhlegarreta commented Aug 2, 2023

thewtex commented Sep 7, 2023

DOC: Update Doxygen XML for ITK 5.3.0 #411

DOC: Update Doxygen XML for ITK 5.3.0 #411

Conversation

thewtex commented Jan 8, 2023 • edited Loading

jhlegarreta left a comment • edited Loading

Choose a reason for hiding this comment

thewtex commented Jan 9, 2023

jhlegarreta commented Jan 9, 2023 • edited Loading

thewtex commented Jan 9, 2023

jhlegarreta commented Jan 9, 2023 • edited Loading

tbirdso commented Jan 9, 2023

jhlegarreta commented Jan 10, 2023

jhlegarreta commented Jan 10, 2023 • edited Loading

jhlegarreta commented Jan 12, 2023

tbirdso commented Jan 12, 2023

jhlegarreta commented Jan 12, 2023 • edited Loading

thewtex commented Jan 12, 2023

thewtex commented Jul 24, 2023

jhlegarreta commented Jul 27, 2023 • edited Loading

jhlegarreta commented Aug 1, 2023

jhlegarreta commented Aug 2, 2023

thewtex commented Sep 7, 2023

thewtex commented Jan 8, 2023 •

edited

Loading

jhlegarreta left a comment •

edited

Loading

jhlegarreta commented Jan 9, 2023 •

edited

Loading

jhlegarreta commented Jan 9, 2023 •

edited

Loading

jhlegarreta commented Jan 10, 2023 •

edited

Loading

jhlegarreta commented Jan 12, 2023 •

edited

Loading

jhlegarreta commented Jul 27, 2023 •

edited

Loading