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).

[bonjourmauko]

Hello @MattiSG !

Since #264, sphinx tools have evolved. In particular, thanks to #312, documentation will no longer be extracted for types, but only actual type annotations (this has been source of many many bugs).

Concerning style, there are three main formats: google, numpy, and PEP. I'm agnostic on which one, as all three can be linted programmatically (I personally use google, that is how I check my changes).

Concerning sphinx, I do a round-trip here now each time I add documentation in core. By default, sphinx.napoleon understands the three styleguides above, but bugs are somewhat unpredictable.

I don't have a better idea for now.