{"action":"opened","issue":{"url":"https://api.github.com/repos/dask/dask/issues/3265","repository_url":"https://api.github.com/repos/dask/dask","labels_url":"https://api.github.com/repos/dask/dask/issues/3265/labels{/name}","comments_url":"https://api.github.com/repos/dask/dask/issues/3265/comments","events_url":"https://api.github.com/repos/dask/dask/issues/3265/events","html_url":"https://github.com/dask/dask/issues/3265","id":303943048,"number":3265,"title":"Improving docstring wrapping with NumPy functions","user":{"login":"jakirkham","id":3019665,"avatar_url":"https://avatars1.githubusercontent.com/u/3019665?v=4","gravatar_id":"","url":"https://api.github.com/users/jakirkham","html_url":"https://github.com/jakirkham","followers_url":"https://api.github.com/users/jakirkham/followers","following_url":"https://api.github.com/users/jakirkham/following{/other_user}","gists_url":"https://api.github.com/users/jakirkham/gists{/gist_id}","starred_url":"https://api.github.com/users/jakirkham/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jakirkham/subscriptions","organizations_url":"https://api.github.com/users/jakirkham/orgs","repos_url":"https://api.github.com/users/jakirkham/repos","events_url":"https://api.github.com/users/jakirkham/events{/privacy}","received_events_url":"https://api.github.com/users/jakirkham/received_events","type":"User","site_admin":false},"labels":[{"id":386719598,"url":"https://api.github.com/repos/dask/dask/labels/documentation","name":"documentation","color":"f9d0c4","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2018-03-09T18:51:00Z","updated_at":"2018-03-09T18:51:00Z","closed_at":null,"author_association":"MEMBER","body":"We often reuse NumPy functions' docstrings. This is convenient as we don't take up maintaining docstrings (or more likely allowing them to go stale) when we don't have anything new to add. However there are few downsides to this approach (and possibly others I'm unaware of).\r\n\r\n1. NumPy versions show up (very confusing to users). ( https://github.com/ioam/holoviews/pull/2424#issuecomment-371896217 )\r\n2. Arguments show up that are not fully or at all supported (also very confusing to users). ( https://github.com/dask/dask/issues/2946 )\r\n3. Examples use NumPy instead of Dask.\r\n\r\nMainly these sorts of things confuse new users and leave them wondering about what Dask actually supports. This is not a great situation for us to be in. There are a few ways we can improve this.\r\n\r\n1. Manually copy and tweak docstrings when they deviate.\r\n2. Scrub things in our wrapper function (e.g. `versionadded`, missing args, examples).\r\n3. Add a note to the docs pointing out how the docstrings are made.\r\n4. Add any missing behavior (though still need to handle version added).\r\n\r\nThis could be an issue with Pandas too. I don't work with that part of the code enough to know.\r\n\r\nThoughts on this?"}}
{"actor":{"display_login":"jakirkham"}}