Building jrl-cmakemodules documentation is failing on Ubuntu 24.04 LTS

[olivier-stasse]

When going in .docs the following:
make html
is failing with:

sphinx-build -b html -d build/doctrees   . build/html
Running Sphinx v7.2.6

Extension error:
Could not import extension cmake (exception: No module named 'sphinx.util.pycompat')
make: *** [Makefile:53 : html] Erreur 

Googling the error, it is because .docs/cmake.py is outdated.

The cmake version on Ubuntu 24.04 LTS is 3.28.3, then from:
https://github.com/Kitware/CMake/blob/v3.28.3/Utilities/Sphinx/cmake.py
I updated locally the file cmake.py.

It creates the following error on conf.py :

Exception occurred:
  File "cmake/.docs/conf.py", line 333, in setup
    app.add_stylesheet("css/cmake.css")

It can be easily fix by using add_css_file instead.

I will propose a PR to fix the matter.
Let me know if this update is problematic.

[olivier-stasse]

Actually the .. cmake-module:: sphinx directive does not work on my machine.
More precisely it does not include ../../base.cmake as it supposed to be.
And the corresponding documentation is not included.
Regarding the current state of the documentation website, it seems that it was not working before.

Using https://github.com/scikit-build/moderncmakedomain and modifying conf.py does not work either.

Modifying cmake.py to use cmakemodule as the directive works if we also modify the corresponding .docs/pages/base.rst. The headers of base.cmake needs also to be modify according to https://cmake.org/cmake/help/v3.5/manual/cmake-developer.7.html?highlight=sphinx#module-documentation.

I pushed a commit on the PR related to this issue proposing a fix.

You can test with

make html

to check that now rst directives in base.cmake are included.

A simpler solution would be to put the documentation in .docs\pages. It would avoid modifying the working *.cmake files.