如何在PyCharm中自动生成Python API文档

Question

我在PyCharm中有一个Python项目,我想从我的Python代码和文档字符串中自动生成API文档(以HTML的形式).

根据此页面,有许多工具可以生成Python API文档:

• 自动摘要
• 车博士
• PDOC
• 是pydoc
• pydoctor
• Doxygen的

该页面还注意到以下工具"流程文档":

• docutils的
• 狮身人面像

该PyCharm文件说的是docutils的狮身人面像和可以使用"产生格式化的API文档".但是,这似乎是不正确的,因为它们的配置表明这些工具只处理*.rst文件,而不处理*.py文件.

我的问题是:我可以使用PyCharm的DocUtils或Sphinx功能来生成API文档吗？

如果做不到这一点,我可以使用PyCharm的任何功能来做到这一点吗？

如果不这样做,有没有任何工具可以与PyCharm很好地集成？

Answer 1

简而言之，我也偶然发现了这个问题：

我的问题是：我可以使用 PyCharm 的 DocUtils 或 Sphinx 功能来生成 API 文档吗？

不。但是，您可以使用 PyCharm 来快速查看文档 ctrl+Q，它会很好地格式化链接、表格等。

如果做不到这一点，我可以使用 PyCharm 的任何功能来做到这一点吗？

并非如此，PyCharm 只能为函数和方法插入文档存根，但它不能进行 api 发现以自动注释所有内容，也不能创建第一个文档存根。

如果做不到这一点，是否有任何工具可以与 PyCharm 很好地集成？

是的 :) sphinx-apidoc它是一个可以从您的代码自动创建第一个文档的工具。还有鲜为人知的autoapi

您只需指向根目录，瞧它甚至可以包含没有文档字符串的成员。它实际上只是使用自动模块语法创建一个简单的 rst 文档。之后，您可以从 PyCharm 运行 sphinx 任务，并且您拥有代码文档，您甚至可以使用类似的主题sphinx_rtd_theme使其看起来非常漂亮。

示例： sphinx-apidoc -o source/ ../ 假设您在项目中创建了一个 doc 文件夹，然后cd doc使用sphinx-quickstart 上述命令进入父目录以发现任何源文件并记录它们。结果存储在<project>/doc/source文件夹中。在其他文件中，将有一个 modules.rst 将所有自动生成的文件拉到一起。

然后在您的 index.rst 中添加一行 .. toctree:: ... source/modules

编辑

最近我发现了一个新工具，我很快就切换到了它，看到使用pdoc3是多么容易