记录CMake脚本 [英] Documenting CMake scripts

问题描述

我发现自己处于这种情况，我想准确地记录一系列自定义CMake宏和函数，并且想知道如何做。

I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.

只要使用内置的语法和文档脚本，就像这样：

The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:

# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------

这很好。但是，我想使用常见的文档生成器，例如doxygen，也生成可以由任何人读取的外部文档，而无需查看实现（这是一种常见的情况）。

This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone without looking at the implementation (which is a common scenario).

一种方法是编写一个简单的解析器，它直接从CMake脚本生成相应的C / C ++头文件以及相应的签名和文档，可以由doxygen或类似的工具。

One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.

有没有其他方法来使用CMake脚本的文档生成器？

Is there any other way to employ a documentation generator with CMake scripts?

推荐答案

这是我可以得到的最近的。下面用CMake 2.8.10测试。目前，CMake 3.0正在开发中，它将获得基于 Sphinx 和< a href =http://de.wikipedia.org/wiki/ReStructuredText =nofollowtitle =reStructuredText> reStructuredText 。我想这将带来新的方式来记录您的模块。

Here is the closest I could get. The following was tested with CMake 2.8.10. Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.

CMake 2.8可以从您的模块中提取文档，但只有文件开头的文档被考虑。所有文档作为CMake注释添加，从单个＃开始。 Double ## 将被忽略（因此您可以在文档中添加注释）。文档的结尾由第一个非注释行标记（例如空行）

CMake 2.8 can extract documentation from your modules, but only documentation at the beginning of the file is considered. All documentation is added as CMake comments, beginning with a single #. Double ## will be ignored (so you can add comments to your documentation). The end of documentation is marked by the first non-comment line (e.g. an empty line)

第一行给出了模块的简要描述。它必须以 - 开头，并以句点或空行结束。

The first line gives a brief description of the module. It must start with - and end with a period . or a blank line.

# - My first documented CMake module.
# description

或
＃ - 我第一个记录的CMake模块
＃
＃description

or # - My first documented CMake module # # description

在HTML中，以两个或多个空格开头的行（＃）以等宽字体格式化。

In HTML, lines starting with at two or more spaces (after the #) are formatted with monospace font.

示例：

# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake. 
#    
#    FOO( [FILENAME <file>]
#         [APPEND]
#         [VAR <variable_name>]
#    )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given, 
# it even writes baz. 

MACRO( FOO )
 ...
ENDMACRO()

要为您的自定义模块生成文档，请调用

To generate documentation for your custom modules only, call

cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html

设置 CMAKE_MODULE_PATH 允许您定义其他目录以搜索模块。否则，你的模块需要在默认的CMake位置。 - help-custom-modules 将文档生成限制为自定义非CMake标准模块。如果给出一个文件名，文档将写入文件，否则为stdout。如果文件名具有可识别的扩展名，则相应地格式化文档。

Setting CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules need to be in the default CMake location. --help-custom-modules limits the documentation generation to custom, non-CMake-standar modules. If you give a filename, the documentation is written to the file, to stdout otherwise. If the filename has a recognized extension, the documentation is formatted accordingly.

以下格式是可能的：

• 。 html for HTML documentation


• .1 至 .9 for man page


• .docbook for Docbook

• .html for HTML documentation
• .1 to .9 for man page
• .docbook for Docbook
• anything else: plain text

这篇关于记录CMake脚本的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！