Hi,
I was perusing the mypy repo and I discovered that mypy can parse docstrings. That's great! The support, however, is currently pretty basic. For starters, mypy currently only supports the google standard. From looking at the code, my instincts tell me that it might be somewhat fragile when exposed to a lot of real-world docstrings.

First, my motivation for using docstrings to provide typing information is the following:

1. Our company is already doing it throughout our codebase
2. It's nice to include type info alongside the description of an argument, so even with PEP484 now in python 3.5, I'll continue to enforce the use of proper docstrings
3. It works in both python 2 and 3

At this point, the python community semes to have settled on three docstring standards:

• reStructuredText
• google
• numpy

Sphinx supports the first out-of-the-box, with the latter two supported via the very nifty napolean extension, which comes bundled in sphinx-contrib. It works by converting google and numpy docstrings into reStructuredText, which is then parsed using docutils. Napolean is quite thorough, very battle-tested, and just forgiving enough on docstring authors to be usable (supports Return as well as Returns, Yield as well as Yields). Here's the relevant code. Also, handily enough, napolean already supports PEP848-style type hints. It depends on six and pockets but the latter could easily be removed.

My thought was that we could leverage napolean and docutils to get rock-solid parsing of all 3 formats. I'm assuming that adding dependencies to mypy is best avoided, so perhaps it can be installed as an extras_require. e.g. pip install mypy[docparse]. To avoid requiring all of sphinx, we could encourage the authors of napolean to provide the guts of their tool as a separate library (it used to be its own repo before it was consumed by sphinx-contrib).

What do you think? I'm glad to do all the work, including talking with the author of napolean, but I wanted to first see if this is something that the mypy team is open to.

Thanks!