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

Question

Google 快速搜索(...实际上很多相当广泛的 Google 搜索)无法解释如何正确记录 CMake 模块。

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

如何使用 cmake --help-module 的模块？记录在案？

感谢任何帮助。

Answer 1

引自 Brad King(CMake 开发人员电子邮件列表成员)的电子邮件回复:

There is no way to do this. The only reason --help-module exists at all is because prior to 3.0 the documentation was generated by the CMake binary itself, and people were used to the option being available. It is only for builtin modules and only available for legacy reasons, and may one day go away in favor of the man pages and html docs.

The online docs, like those at https://cmake.org/cmake/help/v3.14 do publish a /objects.inv to support intersphinx:

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

This was done on request of some users so I haven't looked into how that works, but one should be able to use sphinx to generate one's own documentation and still cross-reference CMake's online docs.

If you get that working we'd welcome a MR to add docs describing how, perhaps in

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

听起来像使用 Sphinx 是可行的方法。

附加信息:

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

it’s from a Sphinx module that you can find the in the CMake sources Utilities/Sphinx/cmake.py. Or you can install this file using pip:

pip install sphinxcontrib-moderncmakedomain

When configuring Sphinx, you have to name the extensions to use in Sphinx's configuration file (conf.py) and add the name of the extension (sphinxcontrib.moderncmakedomain) to the extensions array.