+1 on plain text style docstrings. If all we require now is the content and formatting to generate docs then the `:markup:` is pretty useless and is noise we should drop.

http://sphinx-doc.org/latest/ext/napoleon.html

And I don't think type-hinting tooling not understanding that format is a good reason to stick with sphinx-style markup (i.e. IntelliJ type annotations warnings). Tool lag shouldn't stop us from getting to a better place. In this regard, we should expect the tooling to catch up to us.