What is the proper way to document a CMake module?

只愿长相守 提交于 2021-02-07 08:55:58

问题


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.


回答1:


Quote from an email response I got from Brad King (member of the CMake Developers email list):

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

It sounds like using Sphinx is the way to go.

Additional info:

How does Sphinx know to go parse that ".cmake" file? Does Sphinx recognize the "cmake-module" keyword in a special way and know what to do with it?

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.




回答2:


Good news: You can use sphinx to document your CMake Modules, and at the same time use Doxygen to document your C++ (or other) source code.

I created an example project which shows how to use the sphinxcontrib-moderncmakedomain in combination with Sphinx and Doxygen to generate Documentation for your C++ Code AND CMake code:

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

It is using the sphinxcontrib-moderncmakedomain package and CMake itself to configure the sphinx conf.py and then run sphinx.

The example is heavily based on the official CMake Documentation from: https://gitlab.kitware.com/cmake/cmake/-/tree/master/Utilities/Sphinx



来源:https://stackoverflow.com/questions/54660549/what-is-the-proper-way-to-document-a-cmake-module

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!