Ale*_*ane 6 python documentation coding-style pep
我已经用Python编写了大约一年的代码,我刚刚在Theano教程中遇到了一些代码中它在文件的顶部声明了一个变量:
__docformat__ = 'restructedtext en'
搜索互联网产生了这个 PEP文档.虽然它仍然没有清楚地解释何时/为什么要指定此变量.
我应该在所有Python代码的顶部声明它吗？
的要点__docformat__是允许python文档生成器工具（例如epydoc）知道如何正确解析模块文档（例如，期望使用哪种标记语言）。
从epydoc文档：
要为模块指定标记语言，应定义一个模块级字符串变量__docformat__，其中包含模块标记语言的名称。标记语言的名称可以可选地后跟语言代码（例如en表示英语）。按照惯例，__docformat__变量的定义紧随模块的文档字符串之后
但是，许多工具epydoc（例如epydoc --docformat restructuredtext）也支持通过命令行指定标记语言（例如），因此并不需要严格包含docformat。无论您的项目或组织使用哪种编码约定，它都更加重要。