结构化的 python 文档字符串，IDE 友好答案

【问题标题】：Structured python docstrings, IDE-friendly结构化的 python 文档字符串，IDE 友好
【发布时间】：2010-12-27 03:22:43
【问题描述】：

在 PHP 中我习惯了 PHPdoc 语法：

/** Do something useful
@param first    Primary data
@return int
@throws BadException
*/
function($first){ ...

- 有点有用的简短参考：当您只需要回忆“那是什么？？”时非常方便，特别是对于 3rd 方库。此外，所有 IDE 都可以在弹出提示中显示此内容。

在 Python 中似乎没有约定：只是纯文本。它描述的很好，但它太长了，不能成为一个摘要。

好吧，就这样吧。但在我的应用程序中，我不想使用成堆的明文。

是否有任何众所周知的约定可以遵循？以及如何记录类属性？！ PyCharm IDE 食谱特别受欢迎:)

在 Python3 中有一个 PEP 3107 用于功能注释。这对 2.x（特别是 2.6）没有用

还有一个 PEP 0287 用于 reStructuredText：花哨但仍然没有结构化。

【问题讨论】：

【解决方案1】：

我使用epydoc。它支持 reStructured Text 中的 cmets，并从这些 cmets 生成 HTML 文档（类似于 javadoc）。

【讨论】：

【解决方案2】：

numpydoc 标准定义明确，基于 reStructuredText（这是 python 生态系统中的标准），并集成了 Sphinx。为 PyCharm 编写一个可以消化 numpydoc 的插件应该相对简单。

【讨论】：