为 Python 类制作文档 [关闭]答案

【问题标题】：Producing documentation for Python classes [closed]为 Python 类制作文档 [关闭]
【发布时间】：2010-09-28 05:30:17
【问题描述】：

我即将开始一个项目，我将是唯一一个编写实际代码的人，两名经验不足的程序员（害怕认为自己有经验！）将观察整个程序并提出建议。

是否有一个好的（免费）系统可以用来根据我编写的代码为类和函数提供文档？这可能对他们掌握数据结构有很大帮助。

【问题讨论】：

尝试了建议后，我将使用 epydoc。

标签： python data-structures documentation

【解决方案1】：

我使用epydoc 从嵌入式文档字符串生成 Python 模块的文档。它非常易于使用，并且可以生成多种格式的漂亮输出。

【讨论】：

epydoc 真的很好。除此之外，如果方法被修饰，我没有找到绕过方法签名的方法。如果文档被修饰，文档会显示错误的方法签名。临时解决方案是 - 我在生成文档时禁用自省并且只进行解析。你知道解决办法吗？

【解决方案2】：

python.org 现在使用 sphinx 作为它的文档。

我个人更喜欢 sphinx 的输出而不是 epydoc。我也觉得重组后的文本在文档字符串中比 epydoc 标记更容易阅读。

【讨论】：

同意。此外，标准库正在使用它这一事实使其成为我心中的事实上的标准。
我尝试使用 sphinx，但在使用之前，它似乎是另一种本身需要学习的标记。既然你说你喜欢它，你能给我一些简单教程的链接吗？我想再试一次。
@JV - 我没有经常使用 sphinx，但我花了几个小时查看它生成的文档。这是另一种标记，但它基于 reStructuredText，这是相当常见的（恕我直言，直观）。我发现他们的文档非常好 - 但我必须坐下来通读一遍。
Sphinx 不像 epydoc 那样自动生成 API。
@dowski: Sphinx 有一个autodoc 插件，允许您从文档字符串中提取文档。

【解决方案3】：

Sphinx 可以用于生成非常冗长和信息丰富的文档，这些文档超出了简单的 API 文档所提供的范围。然而，在许多情况下，您最好为此类文档使用 wiki。还可以考虑编写功能测试来演示代码的使用，而不是用文字记录如何使用代码。

Epydoc 非常擅长扫描您的文档字符串并查看您的代码以生成 API 文档，但不一定擅长提供更深入的信息。

为一个项目同时拥有两种类型的文档是有好处的。但是，如果您遇到时间紧迫的问题，拥有良好的测试覆盖率和有意义的测试总是比文档更有益。

【讨论】：

我同意将 Design Doco 放入 wiki。链接允许您通过在任何地方嵌入链接/URL 来交叉引用代码和测试的需求。 Wiki 易于编写，每个人都可以维护它。版本控制和编辑争用是自动处理的（在许多 wiki 包中）。大多数 wiki 包都是跨平台的，而且是免费的！
我也同意自动化测试的好处。如果一张图片值 1000 字，那么一个示例必须至少值 5000 字。
程序员可以并且应该在代码中交流如何编写代码 ;-) 干杯。基思。

【解决方案4】：

我在我的项目中使用 Sphinx，不仅因为它看起来不错，还因为 Sphinx 鼓励编写文档供人类阅读，而不仅仅是计算机。

我发现像 epydoc 这样的工具生成的 JavaDoc 风格的文档读起来很让人难过。程序员不自觉地“记录”参数和返回类型的情况经常发生，因为否则 API 文档中会出现空白。所以你最终得到了这个代码行（它应该看起来像 Java，但是我写 Java 已经有一段时间了，所以它可能无法编译......）

/**
 * Set the name.
 *
 * @param firstName the first name.
 * @param lastName the last name.
 */
public void setName(String firstName, String lastName) {
  this.firstName = firstName;
  this.lastName = lastName;
}

在这个所谓的“文档”中有非常少量的信息。我更喜欢 Sphinx 方式，您（使用 autodoc 插件）只需编写

.. autofunction:: set_name

然后 Sphinx 会在您的文档中添加一行内容

set_name(first_name, last_name)

因此每个 Python 程序员都应该知道发生了什么。

【讨论】：

同意 100%。好的文档的一部分应该在代码中。我经常看到 def setFoo(s, *vars)，然后要么没有文档，要么没有 Sphinx 样式的文档。但大多数情况下，您可以简单地使您的代码更具语义化和自我文档化。

【解决方案5】：

查看can-i-document-python-code-with-doxygen-and-does-it-make-sense 的答案，尤其是那些提到Epydoc 和pydoctor 的答案。

【讨论】：