cmake - What is the proper way to document a CMake module?

Question

A quick Google search (...actually many rather extensive Google searches) have not been able to explain how to properly document a CMake module.

What I'm looking for is a way to document custom CMake modules so that they work with the cmake --help-module <module_name> command. Is there any standard way of doing this? Can anyone point me to some good examples? The documentation process seems oddly.... not well documented. Haha.

How are modules that work with cmake --help-module documented?

Any help is appreciated.

标签： cmakedocumentationcmake-modules

Answer 1

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

没有办法做到这一点。--help-module 存在的唯一原因是因为在 3.0 之前，文档是由 CMake 二进制文件本身生成的，人们已经习惯了可用的选项。它仅适用于内置模块，并且仅出于遗留原因可用，并且有一天可能会消失，取而代之的是手册页和 html 文档。

在线文档，例如https://cmake.org/cmake/help/v3.14上的文档， 确实发布了一个/objects.inv支持 intersphinx：

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

这是应一些用户的要求完成的，所以我没有研究它是如何工作的，但是应该能够使用 sphinx 生成自己的文档，并且仍然可以交叉引用 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) 添加到 extensions 数组。