Python 中的“__docformat__”是做啥用的？

Posted 2023-04-18

【中文标题】Python 中的“__docformat__”是做啥用的？

【英文标题】：What is "__docformat__" used for in Python?Python 中的“__docformat__”是做什么用的？

【发布时间】：2015-11-19 23:14:06

【问题描述】：

我已经使用 Python 编码大约一年了，我刚刚在 Theano tutorial 中遇到了一些代码，它在文件顶部声明了一个变量：

__docformat__ = 'restructedtext en'

搜索互联网产生了this PEP 文档。虽然它仍然没有清楚地解释您何时/为什么要指定此变量。

我应该在所有 Python 代码的顶部声明它吗？

【参考方案1】：

__docformat__ 的重点是允许诸如 epydoc 之类的 python 文档生成器工具知道如何正确解析模块文档（例如，期望哪种标记语言）。

来自epydoc docs：

要为模块指定标记语言，您应该定义一个模块级字符串变量__docformat__，其中包含模块标记语言的名称。标记语言的名称可以选择后跟语言代码（例如 en 表示英语）。按照惯例，__docformat__ 变量的定义紧跟在模块的文档字符串之后

但是，epydoc 等许多工具也支持通过命令行指定标记语言（例如 epydoc --docformat restructuredtext），因此不需要包含 docformat。更多的是您的项目或组织的编码约定。

【讨论】：

如果这一行在注释中而不是定义实际字符串，这意味着什么？