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

Question

我在PyCharm中有一个Python项目，我想从我的Python代码和文档字符串自动生成API文档（以HTML形式）。根据此页面，有许多工具可以生成Python API文档：

- autosummary - autodoc - pdoc - PyDoc - pydoctor - Doxygen

该页面还指出以下工具“处理文档”：

- DocUtils - Sphinx PyCharm文档表示可以使用DocUtils和Sphinx来“生成格式化的API文档”。但是，这似乎是不正确的，因为它们的配置表明这些工具仅处理*.rst文件，而不是*.py文件。

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

如果不行，我能否使用PyCharm的其他功能来完成这个任务？

如果还不行，有没有一些工具可以与PyCharm很好地集成来完成这个任务？

- dln385

---

Sphinx 处理 *.rst 文件（而不是直接处理 *.py 文件）的说法是正确的。为了生成 API 文档（通过从 Python 模块中提取信息），您需要使用 autodoc Sphinx 扩展，该扩展提供 automodule 和其他相关指令。 - mzjn

一个完整的Sphinx相当复杂。因此，我在这里写了我的Sphinx故事（使用PyCharm工作）：使用它，分享它。https://dev59.com/C6Xja4cB1Zd3GeqPP1u0#46362065 - Ferhat

Answer 1

我也遇到过这个问题，简单来说：

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

不行。但是你可以使用PyCharm快速查看文档 ctrl+Q，并且它会以漂亮的格式呈现链接、表格等。

如果不能，我能否使用PyCharm的任何功能来完成这个任务？

不太行，PyCharm只能为函数和方法插入文档存根，但它无法进行API发现以自动注释所有内容，也无法创建rst文档存根。

如果还不行，是否有任何工具能够与PyCharm良好集成并完成此任务？

有 :) sphinx-apidoc 是一个工具，可以从你的代码自动生成rst文档。还有一个较少人知道的工具autoapi

你只需指向根目录，就可以创建一个简单的rst文档，甚至可以包含没有文档字符串的成员。它实际上只是使用automodule语法创建一个简单的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，我很快就切换到了它，因为它非常容易使用。

- CodeSamurai777