我如何从 boost::python 文档字符串创建 doxygen 文档？

Question

我已经使用 boost::python 为大量 C++ 代码创建了 python 绑定。 python 绑定有这样的文档：

BOOST_PYTHON_MODULE(mymodule)
{
    using namespace boost::python;
    def("foo1", foo1, arg("i"), "foo1 doc");
}

项目的其余部分使用 doxygen 进行了记录。我想知道是否有办法从 python 绑定的文档字符串中生成 doxygen 文档。

对我来说，我似乎有两个选择：

使用魔术工具导入python文件并输出文档。 Sphinx 在一定程度上起作用，因为它的 autodoc 工具实际上加载 python 模块并扫描文档字符串。但是，它没有生成 doxygen 可以使用的输出格式（我认为？）。
写一个转换程序导入BOOST_PYTHON_MODULE。调用帮助（我的模块）。解析输出以生成骨架 python 文件。像往常一样将它们喂入 doxygen。

有没有更好的方法？

Answer 1

从开始，您可以执行以下操作：

1 - 编写 doxygen 文档：

// DocString: foo
/**
 * @brief Foo doc
 * @param i an integer
 * @return something
 *
 */
int foo(int i);

2 - 更新您的绑定文档：

BOOST_PYTHON_MODULE(mymodule)
{
    using namespace boost::python;
    def("foo1", foo1, arg("i"), "@DocString(foo)");
}

3 - 使用如下脚本配置您的文件（在构建链中）：

import re
import sys

def parse_doc_string(istr):
    pattern = re.compile(r'@(\w+)\s+(.*)')
    docstring = list()
    for line in map(lambda s : s.strip(), istr):
        if line == '/**':
            continue
        if line == '*/':
            return docstring
        line = line.lstrip('* ')
        match = pattern.match(line)
        if match:
            docstring.append((match.group(1), match.group(2)))

def extract(istr, docstrings):
    pattern = re.compile(r'^//\s*DocString:\s*(\w+)$')
    for line in map(lambda s : s.strip(), istr):
        match = pattern.match(line)
        if match:
            token = match.group(1)
            docstrings[token] = parse_doc_string(istr)

def format_doc_string(docstring):
    return '\n'.join('{}: {}'.format(k, v) for (k, v) in docstring)

def escape(string):
    return string.replace('\n', r'\n')

def substitute(istr, ostr, docstrings):
    pattern = re.compile(r'@DocString\((\w+)\)')
    for line in map(lambda s : s.rstrip(), istr):
        for match in pattern.finditer(line):
            token = match.group(1)
            docstring = format_doc_string(docstrings[token])
            line = line.replace(match.group(0), escape(docstring))
        print(line, file=ostr)

if __name__ == '__main__':
    sourcefile = sys.argv[1]
    docstrings = dict()
    with open(sourcefile) as istr:
        extract(istr, docstrings)
    with open(sourcefile) as istr:
        with sys.stdout as ostr:
            substitute(istr, ostr, docstrings)

它将替换您的绑定：

def("foo1", foo1, arg("i"), "brief: Foo doc\nparam: i an integer\nreturn: something");

我如何从 boost::python 文档字符串创建 doxygen 文档？

How can I create doxygen docs from boost::python docstrings?

python

boost

doxygen

boost-python

python-sphinx