记录 CMakeLists.txt 和自定义或本地 .cmake 文件答案

【问题标题】：Documenting CMakeLists.txt and custom or local .cmake files记录 CMakeLists.txt 和自定义或本地 .cmake 文件
【发布时间】：2016-04-05 00:44:43
【问题描述】：

记录我的项目CMakeLists.txt 文件和本地项目.cmake 文件的好方法是什么？有一个两年前的问题/答案Documenting CMake scripts 我基本上是在这里再次问。答案包含语句

目前，CMake 3.0 正在开发中，它将获得一个基于 Sphinx 和 reStructuredText 的新文档系统。我想这会带来新的方式来记录你的模块。

我看过cmake developer documentation，但是这个新的文档系统似乎是针对cmake本身的文档。我看不到如何使用它来记录我的用户定义项目CMakeLists.txt 文件或本地.cmake 文件。

我希望由于 cmake 项目内部有各种 sphinx 指令和角色，因此作为用户，我可以通过某种方式利用 sphinx 的这种内部用法。我希望能够在我的CMakeLists.txt 文件和本地.cmake 文件中包含一些标记，而无需重新发明轮子。其他项目也有相关的努力。例如，ROS catkin 项目似乎提供了我见过的最完整的方法，但对于非 ROS 项目来说，这是相当重量级的，不容易使用。（例如，查看他们的extracted cmake api page。）最简单的是sphinx-contrib cmakedomain，但它依赖于单独的第一个源文档，而不是带有标记cmets 的autodoc 方法。

也许这是 cmake 列表的问题，但我希望有人在监视 StackOverflow。

【问题讨论】：

我认为这与 CMake 无关，与 sphinix 本身有关。您是否尝试阅读有关它的使用教程？
是的，我知道如何使用 sphinx。但我不知道如何使用 cmake 3 新文档系统 来记录我的CMakeLists.txt 或其他.cmake 文件。 cmake 文档系统似乎是用于记录 cmake，而不是让用户记录其项目特定的 cmake 文件。

标签： cmake documentation python-sphinx

【解决方案1】：

尽管有引用，但我认为 CMake 中与 Sphinx 相关的代码对用户没有用处。我和你有同样的经历，我项目的 CMake 与 CMake 文档中使用的 Sphinx 代码不匹配。

只需使用普通的 Sphinx 并创建自己的模板。

【讨论】：

我希望由于 cmake 项目内部具有各种 sphinx 指令和角色，因此作为用户，我可以通过某种方式利用它们而无需重新发明轮子。我将在我的问题中添加此说明。
@Phil：当然，我是这样理解你的问题的。对于我的项目，这没有成功。不幸的是。

【解决方案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 文档

另请参阅此处的相关问题： What is the proper way to document a CMake module?

【讨论】：