{"action":"opened","issue":{"url":"https://api.github.com/repos/python/mypy/issues/1840","repository_url":"https://api.github.com/repos/python/mypy","labels_url":"https://api.github.com/repos/python/mypy/issues/1840/labels{/name}","comments_url":"https://api.github.com/repos/python/mypy/issues/1840/comments","events_url":"https://api.github.com/repos/python/mypy/issues/1840/events","html_url":"https://github.com/python/mypy/issues/1840","id":164688654,"number":1840,"title":"More robust docstring support","user":{"login":"chadrik","id":63251,"avatar_url":"https://avatars.githubusercontent.com/u/63251?v=3","gravatar_id":"","url":"https://api.github.com/users/chadrik","html_url":"https://github.com/chadrik","followers_url":"https://api.github.com/users/chadrik/followers","following_url":"https://api.github.com/users/chadrik/following{/other_user}","gists_url":"https://api.github.com/users/chadrik/gists{/gist_id}","starred_url":"https://api.github.com/users/chadrik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chadrik/subscriptions","organizations_url":"https://api.github.com/users/chadrik/orgs","repos_url":"https://api.github.com/users/chadrik/repos","events_url":"https://api.github.com/users/chadrik/events{/privacy}","received_events_url":"https://api.github.com/users/chadrik/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2016-07-09T22:27:46Z","updated_at":"2016-07-09T22:27:46Z","closed_at":null,"body":"Hi,\r\nI 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. \r\n\r\nFirst, my motivation for using docstrings to provide typing information is the following:\r\n 1. Our company is already doing it throughout our codebase\r\n 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\r\n 3. It works in both python 2 and 3\r\n\r\nAt this point, the python community semes to have settled on three docstring standards:\r\n- reStructuredText\r\n- google\r\n- numpy\r\n\r\nSphinx supports the first out-of-the-box, with the latter two supported via the very nifty [napolean extension](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/), which comes bundled in sphinx-contrib. It works by converting google and numpy docstrings into reStructuredText, which is then parsed using docutils.  It is quite thorough, very battle-tested, and *just* forgiving enough on docstring authors (supports `Return` as well as `Returns`, `Yield` as well as `Yields`).  Here's the [relevant code](https://bitbucket.org/birkenfeld/sphinx-contrib/src/197c13830fc8452c1438b00047945a172484c778/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default).  Also, handily enough, napolean already [supports PEP848-style type hints](https://bitbucket.org/birkenfeld/sphinx-contrib/issues/104/napoleon-conform-to-pep-484-type-hints-in).  It depends on `six` and [pockets](https://pypi.python.org/pypi/pockets/0.2) but the latter could easily be removed. \r\n\r\nMy 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). \r\n\r\nWhat 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.\r\n\r\nThanks!\r\n\r\n\r\n\r\n"}}
{"actor":{"display_login":"chadrik"}}