问题描述
我使用boost :: python为大量的C ++代码创建了python绑定。 python绑定有这样的文档:
BOOST_PYTHON_MODULE(mymodule)
{
using namespace boost::python;
def("foo1", foo1, arg("i"), "foo1 doc");
}
该项目的其余部分记录了doxygen。 我想知道是否有办法从python绑定的docstrings生成doxygen文档。
对我而言,似乎我有两个选择:
- 使用魔术工具导入python文件并输出文档。 Sphinx在某种程度上起作用,因为它的autodoc工具实际上加载了python模块并扫描了文档字符串。 但是,它没有产生doxygen可以使用的输出格式(我想?)。
- 编写转换过程以导入BOOST_PYTHON_MODULE。 致电帮助(mymodule)。 解析输出以生成骨架python文件。 像往常一样将它们喂入氧气中。
有没有更好的办法?
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");