来自 C++ 项目的 Python 代码的类似 Doxygen 的文档

编程问答 2022-05-25

问题描述

我已经研究这个 C++ 库（使用 C++17）有一段时间了。我的大多数用户都希望它用于 Python，因为他们不知道 C++，所以我不得不为 Python 编写一个库的接口。为此，我选择使用 SWIG。

不用说，在开发过程中我编写了库的文档。我是用Doxygen的评论写的（我目前使用的Doxygen版本是1.9.1），例如

/**
 * @brief Summary of a function's behavIoUr.
 *
 * A few more details...
 * @param param1 Meaning of parameter 1
 * @param param2 Meaning of parameter 2
 * @pre Precondition 1
 * @pre Precondition 2
 * @post Postcondition 1
 * @post Postcondition 2
 * @returns What this function returns is...
 */

我真的不能抱怨 Doxygen 生成 html 文件：C++ 文档生成很好，满足我的所有需求。

现在我想要 Python 接口的文档，因为想要 Python 库的用户不知道任何 C++（或者我被告知）。我的意思是：我希望为我的用户（如果可能）提供在 C++ html 中导航库文档的可能性，但是对于 Python，即——如下文更详细的解释——没有 {{ 1}}，没有 std::vector< >，没有 const，以及所有不适用于 Python 的 C++ 语言特性（附带说明：我可以阻止 Doxygen 记录 {{1} } 但这无助于摆脱所有那么多 & 等）。此外，代替 #ifndef，类似于 std::vector（并且用户将被告知字符串 namspace1::namspace2::function 和 namespace1.namespace2.function 是 Python 模块（这就是 Python 接口的方式）是有组织的）；我通过简单地替换 namespace1 文件中的适当字符串取得了一些进展。例如，我发现可以用 namespace2 替换它的任何 html暂时就足够了。

但这还不够自动化，所以我尝试了以下方法：

  • 用 Doxygen (std::vector&lt; int &gt;) 生成 list_of_ints 文件，用 doxy2swig.py 解析这些文件（它需要 xml 文件并生成一个 GENERATE_XML = YES 文件将 C++ 中的文档放入以 xml 开头的项目列表供 SWIG 使用），然后在我想要记录的每个 .i 中添加一个 %feature("docstring")。我必须说，这个很好：函数做什么的描述和它需要的参数以及它们的描述被添加到 Python 的文档字符串中。但是，除了无法使用 %include "output_of_doxy2swig.i"、.i 或 sphinx 生成没有单词 pydoc left 和 right 的输出（pydoctor 文件） ，html 和 Undocumented 丢失（或忽略）并且模块文档丢失。

  • 使用 SWIG 的 @pre 命令行选项，结果会好一些。就像以前一样，添加了函数和参数的描述，但没有 @post 或 -doxygen 或模块文档。另一个好处是 SWIG 以 @pre 可以用来生成漂亮的 @post 文件的格式写入字符串。

然而，上面两个选项都存在问题：写成函数的输出类型的类型，即

中的sphinx 
html

有时用 C++ 类型编写。我的意思是，即使在使用 "int" 连接 def function() -> "int": # .... 之后，返回类型也是

std::vector<int>

Python 界面的用户很可能是对 C++ 一无所知的 Python 用户，而 %template(list_int) std::vector<int>; 会让这些用户感到困惑。

我想问你的问题是：

  • 是否有任何选项可以让 SWIG 执行以下操作：
    • 添加模块文档？
    • 将 def function() -> "std::vector< int >": # .... 和 "std::vector< int >" 添加到文档字符串？
    • 生成这样的函数？
    @pre
    其中 @post 是我在 def function() -> "list_int": # .... 文件中编写的 list_int 的接口：std::vector<int>。

非常感谢对以上这些的肯定答案。不管答案如何，我还想再问两个问题。

  • 鉴于 Doxygen 从 C++ 源代码生成的一组 .i 文件，是否有任何工具可以替换 C++ 类型（如 %template(list_int) std::vector<int>;、html、{{1 }}) 与我选择的东西？例如：从 std::vector<> 到 std::pair<,>（稍后我会处理命名）。这将是理想的（即使这样的工具不处理模板），因为所有公式 std::array<,> 也将在 Python 的 std::vector<std::pair<int,std::string>> 文件中呈现（I know sphinx admits mahjax 但我仍然没有t 设法让它工作）。像这样的工具似乎非常方便，因为基本上要做的工作较少，但我对存在一个不抱太大希望。
  • 是否有一些教程/手册/可以逐步解释，并且至少有一个最小的工作示例（我无法找到），如何从与 python 接口的 C++ 源自动生成 python 文档与 swig没有 C++ 类型（如 STL 容器）？或者，也许存在一个不得不面对同样问题的现有项目？例如，Cgal 有 C++ 库的 Python 绑定，但我有一种奇怪的感觉，它没有用 SWIG 包装（但是，如果我错了，请告诉我）。

感谢大家的时间和耐心。我真的希望得到一些肯定的答案，但我已经准备好听到坏消息（特别是关于最后两个）。

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

c++documentationdocumentationdocumentation-generationpythonswigswig