Define how to document Python code

[MattiSG]

We have many pull requests and issues associated to documentation on Core (see openfisca/openfisca-core#1063).
However, these PRs are often blocked due to a lack of clear understanding on how the code should be documented: which metadata and format should be used?
This specification should take into account the extractability of data, as encountered in #264 (comment).