Consolidating the config files from the main ITK directory and the wrapping directory

[albert-github]

Consolidating the config files from the main ITK directory and the wrapping directory

Description

Based on #5293 (comment) and the further discussion in #5293

The complete difference between the files:

diff -b -w Utilities/Doxygen/DoxygenConfig.cmake Wrapping/DoxygenConfig.cmake

7c7
< set(DOXYGEN_OUTPUT_DIRECTORY "${ITK_DOXYGEN_OUTPUT_DIR}")
---
> set(DOXYGEN_OUTPUT_DIRECTORY "${ITK_WRAP_DOC_LIBRARY_DIR}")
20,22c20
<     "endsphinx=^^ ^^ ^^"
<     "ITKStartGrouping=@{"
<     "ITKEndGrouping=@}")
---
>     "endsphinx=^^ ^^ ^^")
61,62d58
< set(DOXYGEN_GENERATE_TREEVIEW "YES")
< set(DOXYGEN_DISABLE_INDEX "YES")
76d71
< set(DOXYGEN_MATHJAX_VERSION "MathJax_2")
78d72
< if(ITK_DOXYGEN_SERVER_BASED_SEARCH)
80,82d73
< else()
<   set(DOXYGEN_SERVER_BASED_SEARCH "NO")
< endif()
173,190d163
<
< foreach(
<   _FORMAT IN
<   ITEMS HTML
<         DOCSET
<         CHM
<         QHP
<         ECLIPSEHELP
<         LATEX
<         RTF
<         XML)
<   # map ON/OFF to YES/NO
<   if(ITK_DOXYGEN_${_FORMAT})
<     set(DOXYGEN_GENERATE_${_FORMAT} "YES")
<   else()
<     set(DOXYGEN_GENERATE_${_FORMAT} "NO")
<   endif()
< endforeach()

The config files are used in:
Utilities/Doxygen/CMakeLists.txt and Wrapping/macro_files/itk_end_wrap_module.cmake
in the later there is even the remark:

 # NOTE: The Configuration files should be placed in the itk package directory.

Expected information

One doxygen configuration file

Actual information

2 different configuration files

Versions

master version (993fc93)

[albert-github]

For the normal documentation the target is "Documentation" but I do not see a target for the wrapper documentation.

• How is it possible to build the wrapper documentation?

[dzenanz]

I would assume we need to turn on both ITK_BUILD_DOCUMENTATION and ITK_WRAP_PYTHON. @thewtex might have further insight.

[thewtex]

Enable the CMake configuration options ITK_WRAP_PYTHON and ITK_WRAP_DOC.

[albert-github]

@dzenanz, @thewtex thanks for the answer, I tried:

cmake -G "NMake Makefiles" -DDOXYGEN_EXECUTABLE=...\doxygen.exe -DITK_DOXYGEN_SERVER_BASED_SEARCH=OFF -DITK_WRAP_DOC=ON -DITK_WRAP_PYTHON=ON ..

and

cmake -G "NMake Makefiles" -DITK_BUILD_DOCUMENTATION=ON -DDOXYGEN_EXECUTABLE=...\doxygen.exe -DITK_DOXYGEN_SERVER_BASED_SEARCH=OFF -DITK_WRAP_DOC=ON -DITK_WRAP_PYTHON=ON ..

but I got:

...
-- ITKCommon: Creating itkStreamingImageFilter submodule.
CMake Error at D:/Program Files/CMake/share/cmake-3.22/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
  Could NOT find Python3 (missing: Development.SABIModule) (found suitable
  version "3.12.3", required range is "3.9...3.999")
Call Stack (most recent call first):
  D:/Program Files/CMake/share/cmake-3.22/Modules/FindPackageHandleStandardArgs.cmake:594 (_FPHSA_FAILURE_MESSAGE)
  D:/Program Files/CMake/share/cmake-3.22/Modules/FindPython/Support.cmake:3166 (find_package_handle_standard_args)
  D:/Program Files/CMake/share/cmake-3.22/Modules/FindPython3.cmake:490 (include)
  Wrapping/macro_files/itk_end_wrap_module.cmake:404 (find_package)
  Wrapping/TypedefMacros.cmake:1336 (itk_end_wrap_module)
  Modules/Core/Common/wrapping/CMakeLists.txt:63 (itk_auto_load_and_end_wrap_submodules)

Python version is 3.12.3 but beforehand I saw:

...
-- Found Python3: D:/Programs/Python/Python312/python.exe (found suitable version "3.12.3", required range is "3.9...3.999") found components: Interpreter Development.Module
...

So it looks like I'm missing something, from vllm-project/vllm#5671 (comment) I got the idea to install

python -m pip install python-dev-tools

but this failed on "can't find Rust compiler".

Trying the other suggestion: vllm-project/vllm#5671 (comment) and installed cmake 3.31.6 this seems to solve the SABIModule problem.

• should there be an update warning for the used CMake version?

When I used

cmake -G "NMake Makefiles" -DDOXYGEN_EXECUTABLE=...\doxygen.exe -DITK_DOXYGEN_SERVER_BASED_SEARCH=OFF -DITK_WRAP_DOC=ON -DITK_WRAP_PYTHON=ON ..

I didn't see any documentation target, so I tried:

cmake -G "NMake Makefiles" -DITK_BUILD_DOCUMENTATION=ON -DDOXYGEN_EXECUTABLE=...\doxygen.exe -DITK_DOXYGEN_SERVER_BASED_SEARCH=OFF -DITK_WRAP_DOC=ON -DITK_WRAP_PYTHON=ON ..

but this looks like to build the "normal" documentation.

In both cases I see files like Wrapping/Modules/ITKWatersheds/Doxyfile.ITKWatershedsDoxygen (these are the result files that "have to be changed") but I still have no Idea how I can generate the wrapping documentation.

[thewtex]

@albert-github a few things to try:

• Install newer CMake
• Make sure enable the development options when installing Python

[albert-github]

@thewtex

Sorry for the late response but I was not at home and I couldn't access a computer, thanks for the suggestions.

I already wrote:

Trying the other suggestion: vllm-project/vllm#5671 (comment) and installed cmake 3.31.6 this seems to solve the SABIModule problem.

• should there be an update warning for the used CMake version?

So this part of the problem is solved for me., but I also wrote:

I didn't see any documentation target, so I tried:
...

So the question I posed there is:

• how to build the wrapper documentation.

[thewtex]

@albert-github the documentation is built as part of the wrapping. The extracted Doxygen documentation content is integrated into the python bindings as python docstrings.

[albert-github]

@thewtex
Thanks.
I don't get it yet, are the strings from C++ transferred directly to python docstrings? In that case are the python docstrings used by python or is as part of the wrapping process also a set doxygen documentation based on e.g. Doxyfile.ITKWatershedsDoxygen generated.

• In other words how to generate this ... (make ITKWatershedsDoxygen or make ITKWatersheds-all)

[albert-github]

I've just pushed a proposed patch, pull request #5313

Due to the limited knowledge about the wrapping process and generating its documentation I was only able to do limited testing.
The warnings regarding ITKStartGrouping and ITKEndGrouping are gone, but I still see some warnings regarding the ingroup command.

[thewtex]

@albert-github thanks for the patch!

I don't get it yet, are the strings from C++ transferred directly to python docstrings? In that case are the python docstrings used by python or is as part of the wrapping process also a set doxygen documentation based on e.g. Doxyfile.ITKWatershedsDoxygen generated.

Doxygen is used to generate XML from comments in the C++ sources. This XML is processed to generate the documentation in the python bindings, the python docstrings. See, e.g.

https://github.com/InsightSoftwareConsortium/ITK/blob/master/Wrapping/Generators/Doc/doxy2swig.py