How does cmake-docs use Sphinx to parse comments in CMake files?

Development
1

Excuse me, CMake Team.

I’ve noticed before that many CMake files in Kitware/CMake have comments in the following format in their headers (ex. FindPython.cmake):

#[====================[.rst:

#]====================]

And these comments eventually end up in the CMake Documentation (ex. FindPython). This is similar to how Doxygen parses C/C++ comments. Since I didn’t see that Sphinx Documentation has built-in support for this kind of parsing, I’m guessing that CMake has implemented its own mechanism to parse these types of comments? If so, how?

1 Like
2

We implement a Sphinx extension module that adds a cmake-module directive. The directive is used by each Help/module/*.rst file to parse documentation blocks out of a .cmake file.

2 Likes
3

That’s a pretty handy Sphinx extension. Should admirers just borrow the script in accordance with its BSD 3-Clause License, or is it available in some packaged form (with associated package update semantics)?

4

A ready-to-use pip extension was created here:
https://github.com/scikit-build/moderncmakedomain

1 Like
5

Do the sphinx comments have any relation to the docs used here?

I’ve seen this used many places. Perhaps it’s the legacy format?

6

About the code snippets @Ryanf55 mentioned in ament_package.cmake, I haven’t found a clue, but I guess maybe it is related to this project, CMakePP/CMinx.

Comparing the syntax that CMakePP/CMinx uses, they look so similar:

A simple example taken from CMinx Documentation:

#[[[
# This function has very basic documentation.
#
# This function's description stays close to idealized formatting and does not
# do anything fancy.
#
# :param person: The person this function says hi to
# :type person: string
#]]
function(say_hi_to person)
    message("Hi ${person}")
endfunction()
2 Likes