Fix documentation CI failure

[thewtex]

No description provided.

[tbirdso]

After updating input/output data directories for KeepRegionsAboveLevel on data.kitware.com everything except documentation is passing 🤷‍♂️

Updating the issue title to reflect remaining work.

[tbirdso]

In contrast to CDash reporting, CI logs show that failure occurs at the Doxygen build step:

2022-03-08T22:09:10.9217174Z [1585/1593] Generating sphinx documentation: html
2022-03-08T22:09:10.9217505Z FAILED: CMakeFiles/build_html 
2022-03-08T22:09:10.9218286Z cd /home/runner/work/bld/ITKEx-build && /home/runner/work/bld/itkpython/bin/sphinx-build -b html -c /home/runner/work/bld/ITKEx-build/Formatting /home/runner/work/bld/ITKEx-build /home/runner/work/bld/ITKEx-build/html
2022-03-08T22:09:10.9218407Z Running Sphinx v4.4.0
2022-03-08T22:09:10.9218418Z 
2022-03-08T22:09:10.9218571Z Extension error (doxylink.doxylink):
2022-03-08T22:09:10.9219106Z Handler <function setup_doxylink_roles at 0x7fe8b838fdc0> for event 'builder-inited' threw an exception (exception: no element found: line 1, column 0)
2022-03-08T22:09:10.9222461Z [1586/1593] Building CXX object src/Segmentation/ConnectedComponents/LabelConnectComponentsInGrayscaleImage/CMakeFiles/LabelConnectComponentsInGrayscaleImage.dir/Code.cxx.o
2022-03-08T22:09:10.9222939Z [1587/1593] Building CXX object src/Segmentation/ConnectedComponents/ExtraLargestConnectComponentFromBinaryImage/CMakeFiles/ExtraLargestConnectComponentFromBinaryImage.dir/Code.cxx.o
2022-03-08T22:09:10.9223085Z ninja: build stopped: subcommand failed.
2022-03-08T22:09:10.9223222Z ninja: build stopped: subcommand failed.
2022-03-08T22:09:10.9223342Z Command exited with the value: 1

I am able to recreate this failure locally, will continue to investigate.

[tbirdso]

From tracing through the doxylink error, it looks like CMake is trying to fetch an archive from public.kitware.com which no longer exists:

DownloadDoxygenTAG.CMake

References broken link: https://public.kitware.com/pub/itk/NightlyDoxygen/InsightDoxygenDocTag.gz

@thewtex could you please verify whether InsightDoxygenDocTag-5.2.0.gz at https://data.kitware.com/#item/60674d8a2fa25629b94769d2 is the correct archive to use?

[tbirdso]

Note that both https://itk.org/files/NightlyDoxygen/InsightDoxygenDocTag.gz and data.kitware.com/.../InsightDoxygenDocTag-5.2.0.gz appear to be valid archives allowing docs to build successfully. Awaiting word on the appropriate archive to fetch.

[dzenanz]

The first one is the right one.

[tbirdso]

50 CDash warnings are remaining in regards to duplicate linkage at breathelink tags:

ITKEx-build/src/Bridge/VtkGlue/ConvertAnitkImageTovtkImageData/Documentation.rst:131: WARNING: Duplicate C++ declaration, also defined at src/Bridge/VtkGlue/ConvertAnRGBitkImageTovtkImageData/Documentation:129.
...

Each warning points to a :: breathelink entry in a .rst file where other .rst files also have :: breathelink entry for the same class.

@thewtex Perhaps you could weigh in on whether you think this is an issue in https://github.com/thewtex/breathelink? From what I can tell so far the no-link option is intended to address this case so that duplicate declarations are not linked, but it looks like the option is being set correctly in breathelink.py.

[thewtex]

@tbirdso perhaps breathelink can be improved? Yes, the intention is to have multiple descriptions of the relevant classes in each example for quick reference. Maybe these warnings are the result of updating Sphinx.

[tbirdso]

Maybe these warnings are the result of updating Sphinx.

This is very possible. The first instance of this warning that I can find is from February 2nd, while Sphinx was updated from 3.0.4 to 4.4.0 in 7c77f79 on January 27th. It looks like we haven't had a successful docs build since summer 2021.

I will try downgrading Sphinx locally and building.

EDIT: I still see the warnings with Sphinx 3.0.4, though the warning message is slightly different:

ITKSphinxExamples-dev/src/Bridge/VtkGlue/ConvertAnitkImageTovtkImageData/Documentation.rst:131: WARNING: Duplicate declaration, template itk::ImageToVTKImageFilter : public itk::ProcessObject

Will continue investigating.

[tbirdso]

Relevant discussion in breathe issue 378 indicates that the no-link option for cpp classes is nonfunctional and the related noindex option was actually removed from Sphinx in sphinx-doc/sphinx#7895. It seems that cpp:alias may be the correct directive to use here as per sphinx-doc/sphinx#5901. I will investigate how this could be supported with breathelink.

[tbirdso]

@thewtex @dzenanz Note that the remaining warnings are about the behind-the-scenes docs structure and should not block the release of documentation as it is currently doing in CI. Is there a CMake/CTest/Github Actions flag that we can use to allow docs CI to ignore warnings (but not errors) and proceed with publishing? Have been unsuccessful in my search for suppressing warnings so far.

[tbirdso]

Note that it looks like this is a duplicate of #266 , with a slightly updated warning message via the Sphinx update to v4.4.0. As the scope of this issue (#324) has changed a couple of times I think it will be best to consolidate discussion in #266. Closing #324 as a duplicate.