python - "__docformat__"在 Python 中有什么用？

Question

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

__docformat__ = 'restructedtext en'

网上搜索出this政治公众人物文件。虽然它仍然没有清楚地解释您何时/为什么要指定此变量。

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

Answer 1

__docformat__ 的要点是允许 python 文档生成器工具，例如 epydoc了解如何正确解析模块文档(例如，期望使用哪种标记语言)。

来自epydoc docs :

To specify the markup language for a module, you should define a module-level string variable __docformat__, containing the name of the module's markup language. The name of the markup language may optionally be followed by a language code (such as en for English). Conventionally, the definition of the __docformat__ variable immediately follows the module's docstring

不过，epydoc等很多工具也支持通过命令行指定标记语言(例如epydoc --docformat restructuredtext)，所以没有严格的必要包括文档格式。更重要的是您的项目或组织的编码约定。