python - Python 中的“__docformat__”是做什么用的？

Question

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

__docformat__ = 'restructedtext en'

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

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

Answer 1

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

从epydoc 文档：

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

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