Documenting CMakeLists.txt and user or local .cmake files

Question

What are some good ways to document CMakeLists.txt project CMakeLists.txt and local .cmake project .cmake ? There is a two-year question / answer Documentation of CMake scripts , which I essentially ask here again. Answer contains statement

CMake 3.0 is under development and will receive a new documentation system based on Sphinx and reStructuredText. I assume this will lead to new ways of documenting your modules.

I reviewed the cmake developer documentation , but this new documentation system seems to focus on the cmake documentation itself. I do not see how I can use this to document my CMakeLists.txt project CMakeLists.txt or local .cmake files.

I hope that since the cmake project inside has various sphinx directives and roles that were somehow as a user, I could take advantage of this internal use of sphinx. I would like to be able to markup in CMakeLists.txt files and local .cmake files without having to reinvent the wheel. Other projects have corresponding efforts. For example, the ROS catkin project seems to offer the most comprehensive approach I've seen, but it is a pretty heavy weight that is not easy to use for non-ROS projects. (As an example, consider their extracted cmake api page ). The simplest is sphinx-contrib cmakedomain, but it depends on the individual source source document, and not on the autodoc approach with markup comments.

This may be a question for the cmake list, but I was hoping someone controlled StackOverflow.

Answer 1

Despite the quote, I don’t think the CMph related code from CMake is useful to users. I made the same experience as you did, my CMake project didn’t work very well with the Sphinx code used in the CMake documentation.

Just use simple Sphinx and create your own templates.