记录CMake模块的正确方法是什么？

Question

快速的Google搜索（实际上实际上是许多相当广泛的Google搜索）无法解释如何正确记录CMake模块。

我正在寻找一种记录自定义CMake模块的方法，以便它们与cmake --help-module <module_name>命令一起使用。有什么标准的方法可以做到这一点吗？谁能指出一些好的例子？记录过程似乎很奇怪。...记录不充分。哈哈。

如何记录与cmake --help-module兼容的模块？

感谢您的帮助。

Answer 1

我从Brad King（CMake开发人员电子邮件列表的成员）收到的电子邮件回复中引用：

  

没有办法做到这一点。 --help-module存在的唯一原因   完全是因为3.0之前的文档是由   CMake二进制文件本身，人们习惯了   可用。仅适用于内置模块，仅适用于   遗留的原因，可能有一天将不再使用手册页   和html文档。

     

在线文档，例如https://cmake.org/cmake/help/v3.14上的文档   确实发布/objects.inv以支持狮身人面像：

     

http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

     

这是应一些用户的要求完成的，因此我没有研究如何   可以，但是应该可以使用狮身人面像生成自己的   自己的文档，仍然可以交叉引用CMake的在线文档。

     

如果您能做到这一点，我们将欢迎MR为您添加说明方式的文档，   也许在

     

https://gitlab.kitware.com/cmake/cmake/blob/master/Help/dev/documentation.rst

听起来像是使用Sphinx是一种方法。

其他信息：

Sphinx如何知道去解析“ .cmake”文件？ Sphinx是否以特殊方式识别“ cmake-module”关键字并知道如何处理？

  

来自Sphinx模块，您可以在CMake的源程序Utilities / Sphinx / cmake.py中找到。或者您可以使用pip安装此文件：

     

pip install sphinxcontrib-moderncmakedomain

     

在配置Sphinx时，您必须命名要在Sphinx的配置文件（conf.py）中使用的扩展名，并将扩展名（sphinxcontrib.moderncmakedomain）添加到扩展名数组。

Answer 2

好消息：您可以使用 sphinx 来记录您的 CMake 模块，同时使用 Doxygen 来记录您的 C++（或其他）源代码。

我创建了一个示例项目，展示了如何结合使用 sphinxcontrib-moderncmakedomain 与 Sphinx 和 Doxygen 来为您的 C++ 代码和 CMake 代码生成文档：

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

它使用 sphinxcontrib-moderncmakedomain 包和 CMake 本身来配置 sphinx conf.py，然后运行 ​​sphinx。

该示例主要基于来自 https://gitlab.kitware.com/cmake/cmake/-/tree/master/Utilities/Sphinx

的官方 CMake 文档