python - 有没有一种为 swig 接口生成文档的好方法？

Question

我想知道是否有任何好的技术可以在界面上构建/维护文档。

我正在使用 swig 构建从 c++ 代码到 python 的接口；大多数情况下，我只是 %包括 c++ 头文件。我要处理至少几十个类和上百个函数，所以首选自动化工具。

理想情况下，我想在 c++ 标头中使用 doxygen 格式的注释来填充 python 类/方法中的文档字符串。

或者，生成单独的文档（在 ascii、html...中）也很有用。swig 的早期版本（1.3 和更早版本）似乎支持这种功能，但我看不到用 2.0 实现它的方法。

是否有任何有用的（自动化）技术来记录界面？

score 9 · Accepted Answer

要将您的 doxygen 注释添加到 python 文件中，在网络上有一个名为 doxy2swig.py 的 python 工具，如此处所述。

从您的代码创建 xml 文档。然后使用工具：

doxy2swig.py index.xml 文档.i

并通过在您的 swig 界面文件中导入 documentation.i

%import "文档.i"

它完成了。

score 2 · Accepted Answer

SWIG 2.0有一些%feature("autodoc")进展，我认为目前为止。

例如：

%module test

%feature("autodoc", "3");

void foo (int *a, void *bar, double epsilon);

导致插入一些模糊不清的文档。

如果这还不够，我认为下一个最简单的步骤是使用%pythonprepend制作一个足够独特或类似的标记，以便sed在 SWIG 自动运行后将文档插入界面：

%pythonprepend foo "MARKER"

进而：

sed -ei 's/MARKER/some documentation' test.py

%pythonprepend通过使用（Python？）脚本查看 Doxygen 输出来生成标记并在运行 SWIG 后替换它们，您可以在哪里找到函数。

2 回答 2