What is "__docformat__" used for in Python?

Question

I have been coding for about a year now in Python and I have just come across some code in a Theano tutorial that declares a variable at the top of the file:

__docformat__ = 'restructedtext en'

Searching the internet produced this PEP documentation. Although it still doesn't clearly explain when / why you would want to specify this variable.

Should I be declaring it at the top of all my Python code?

Answer 1

The point of the __docformat__ is to allow python documentation generator tools such as epydoc to know how to properly parse the module documentation (e.g. which markup language to expect).

From the 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

However, many tools such as epydoc also support specifying the markup language via command-line (e.g. epydoc --docformat restructuredtext), so there is no strict need to include the docformat. It's more just whatever the coding conventions are for your project or organization.