从Javadoc迁移到Python文档

Question

我已经对Javadoc风格的文档习惯了。浏览各种Python代码示例时，我发现，乍一看，文档似乎缺少很多信息。

好处是：很少看到不言自明的文档。文档字符串通常是一段英文标记语言，与单独的行相融合而不是突出。

坏处是：结合Python的鸭子类型，我发现许多函数对它们所期望的参数并不清楚。没有类型提示（鸭子提示？），通常情况下，了解一下参数应该类似于列表、字符串或流会更好。

当然，Javadoc是为一种低级语言设计的，没有Python强大的内省能力，这可能解释了较少的文档哲学。

有关Python文档标准和最佳实践的建议？

- Koobz

---

这有点开放式的。我已经加上了我正在寻求建议。 - Koobz

需要什么建议呢？您是在编写软件并想提供文档吗？还是在抱怨找不到Python库文档中的内容？“Python...文档似乎缺少很多信息”只是一种抱怨。您遇到了什么困难呢？ - S.Lott

我所指的是源代码文档，它似乎比我使用 Java 和 PHP 时更加简洁。这只是一种观察，并非抱怨，先生。当时我不知道 ReST，结果发现它正是我在寻找的东西。 - Koobz

Answer 1

reStructuredText 格式是为了满足可以嵌入docstrings的Python文档而设计的，因此最好学习reST并使用该格式来格式化您的docstrings。您可能会发现，就像我一样，您随后会使用reST格式来格式化几乎任何文档，但这只是一个副产品 :-)

对于特定的Python代码文档，Sphinx 系统是reST格式的扩展集合，以及呈现文档的构建系统。由于它是为了记录Python本身（包括标准库）而设计的，因此Sphinx允许非常结构化地记录源代码的文档，当然也包括您所询问的函数签名的具体信息。它允许构建全面的文档套件，既可以自动提取，也可以手写，所有这些都使用相同的格式化系统。

如果您仅想从源代码生成文档，则 Epydoc 可从源代码中提取API文档；它也会读取文本的reST格式。

- bignose

---

+1：epydoc在工作方式上非常接近javadoc。使用epytext会感到舒适，因为语法类似。然而，转换为RST并使用Sphinx可以更灵活地生成文档，并具有更好的外观。 - S.Lott