如何在 PyCharm 中自动生成 Python API 文档 [关闭]答案

【问题标题】：How to automatically generate Python API documentation in PyCharm [closed]如何在 PyCharm 中自动生成 Python API 文档 [关闭]
【发布时间】：2016-06-27 22:40:51
【问题描述】：

我在 PyCharm 中有一个 Python 项目，我想从我的 Python 代码和文档字符串中自动生成 API 文档（以 HTML 的形式）。

根据this page，有很多工具可以生成 Python API 文档：

自动摘要
自动文档
文档
PyDoc
医生
氧气

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

DocUtils
狮身人面像

DocUtils 和 Sphinx 可用于“生成格式化的 API 文档”的PyCharm documentation says。然而，这似乎是不正确的，因为their configuration indicates 那些工具只处理*.rst 文件，而不是*.py 文件。

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

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

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

【问题讨论】：

Sphinx 处理 *.rst 文件（而不是直接处理 *.py 文件）是正确的。为了生成 API 文档（通过从 Python 模块中提取信息），您需要使用 autodoc Sphinx 扩展，它提供了 automodule 和其他相关指令。
一个完整的工作狮身人面像是相当复杂的。所以我在这里写了我的狮身人面像故事（使用 PyCharm）：使用它，分享它。 stackoverflow.com/a/46362065/1980180

标签： python pycharm python-sphinx documentation-generation docutils

【解决方案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 pdoc3

【讨论】：