python - 为 Python 类生成文档

Question

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

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

Answer 1

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

Answer 2

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

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

Answer 3

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

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

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

Answer 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 程序员都应该知道发生了什么。

Answer 5

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