Documenting CMakeLists.txt and custom or local .cmake files

Question

What are good ways to document my project CMakeLists.txt files and local project .cmake files? There is a two year old question/answer Documenting CMake scripts that I am essentially asking here again. The answer contains the statement

Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.

I have looked at the cmake developer documentation, but this new documentation system seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project CMakeLists.txt files or local .cmake files.

I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some markup in my CMakeLists.txt files and local .cmake files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their extracted cmake api page.) The simplest, is the sphinx-contrib cmakedomain, but that relies on a separate rst source doc rather than an autodoc approach with markup comments.

Perhaps this is a question for the cmake list, but I was hoping someone was monitoring StackOverflow.

Answer 1

Good news: You can use sphinx to document your CMake Modules, and at the same time use Doxygen to document your C++ (or other) source code.

I created an example project which shows how to use the sphinxcontrib-moderncmakedomain in combination with Sphinx and Doxygen to generate Documentation for your C++ Code AND CMake code:

https://gitlab.com/Pro1/doxygen-cmake-sphinx

It is using the sphinxcontrib-moderncmakedomain package and CMake itself to configure the sphinx conf.py and then run sphinx.

The example is heavily based on the official CMake Documentation from: https://gitlab.kitware.com/cmake/cmake/-/tree/master/Utilities/Sphinx

See also the related question here: What is the proper way to document a CMake module?