Question

我即将开始一个项目，在那里我将是唯一一个做实际代码的人和两个经验不足的程序员（可怕的想象自己经验丰富！）将会一直在观看并对程序提出建议。

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

Answer 1

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

Answer 2

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

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

Answer 3

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

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

为项目提供两种类型的文档都很有道理。但是，如果你遇到时间紧迫，那么获得良好的测试覆盖率和有意义的测试总是比文档更有益。

Answer 4

我将Sphinx用于我的项目，不仅因为它看起来不错，还因为Sphinx鼓励编写 human 的文档来阅读，而不仅仅是计算机。

我找到喜欢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的答案。

为Python类生成文档

5 个答案: