{"action":"created","comment":{"url":"https://api.github.com/repos/pandas-dev/pandas/pulls/comments/173336946","pull_request_review_id":102512612,"id":173336946,"diff_hunk":"@@ -1077,5 +1077,78 @@ The branch will still exist on GitHub, so to delete it there do::\n \n     git push origin --delete shiny-new-feature\n \n+Sharing Docstrings\n+==================\n+\n+Pandas has a system for sharing docstrings, with slight variations, between\n+classes. This helps us keep docstrings consistent, while keeping things clear\n+for the user reading. It comes at the cost of some complexity when writing.\n+\n+Each shared docstring will have a base template with variables, like\n+``%(klass)s``. The variables filled in later on using the ``Substitution``\n+decorator. Finally, docstrings can be appended to with the ``Appender``\n+decorator.\n+\n+In this example, we'll create a parent docstring normally (this is like\n+``pandas.core.generic.NDFrame``. Then we'll have two children (like\n+``pandas.core.series.Series`` and ``pandas.core.frame.DataFrame``). We'll\n+substitute the children's class names in this docstring.\n+\n+.. code-block:: python\n+\n+   class Parent:\n+       def my_function(self):\n+           \"\"\"Apply my function to %(klass)s.\"\"\"\n+           ...\n+           \n+   class ChildA(Parent):\n+       @Substitution(klass=\"ChildA\")\n+       @Appender(Parent.my_function.__doc__)\n+       def my_function(self):\n+           ...\n+\n+   class ChildB(Parent):\n+       @Substitution(klass=\"ChildB\")\n+       @Appender(Parent.my_function.__doc__)\n+       def my_function(self):\n+           ...\n+        \n+The resulting docstrings are\n+\n+.. code-block:: python\n+\n+   >>> print(Parent.my_function.__doc__)\n+   Apply my function to %(klass)s.\n+   >>> print(ChildA.my_function.__doc__)\n+   Apply my function to ChildA.\n+   >>> print(ChildB.my_function.__doc__)\n+   Apply my function to ChildB.\n+\n+Notice two things:\n+\n+1. We \"append\" the parent docstring to the children docstrings, which are\n+   initially empty.\n+2. Python decorators are applied inside out. So the order is Append then\n+   Substitution, even though Substitution comes first in the file.\n+\n+Our files will often contain a module-level ``_shared_doc_kwargs`` with some\n+common substitution values (things like ``klass``, ``axes``, etc).\n+\n+You can substitute and append in one shot with something like\n+\n+.. code-block:: python\n+\n+   @Appender(template % _shared_doc_kwargs)\n+   def my_function(self):\n+       ...\n+\n+where ``template`` may come from a module-level ``_shared_docs`` dictionary\n+mapping function names to docstrings. Wherever possible, we prefer using\n+``Appender`` and ``Substitution``, since the docstring-writing processes is\n+slightly closer to normal.\n+\n+See ``pandas.core.generic.NDFrame.fillna`` for an example template, and","path":"doc/source/contributing.rst","position":74,"original_position":74,"commit_id":"0e43660d96d4f4d8f860643fc1271a603ad2390c","original_commit_id":"0e43660d96d4f4d8f860643fc1271a603ad2390c","user":{"login":"jreback","id":953992,"avatar_url":"https://avatars2.githubusercontent.com/u/953992?v=4","gravatar_id":"","url":"https://api.github.com/users/jreback","html_url":"https://github.com/jreback","followers_url":"https://api.github.com/users/jreback/followers","following_url":"https://api.github.com/users/jreback/following{/other_user}","gists_url":"https://api.github.com/users/jreback/gists{/gist_id}","starred_url":"https://api.github.com/users/jreback/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jreback/subscriptions","organizations_url":"https://api.github.com/users/jreback/orgs","repos_url":"https://api.github.com/users/jreback/repos","events_url":"https://api.github.com/users/jreback/events{/privacy}","received_events_url":"https://api.github.com/users/jreback/received_events","type":"User","site_admin":false},"body":"can you point to actual code","created_at":"2018-03-09T00:42:27Z","updated_at":"2018-03-09T00:42:54Z","html_url":"https://github.com/pandas-dev/pandas/pull/20016#discussion_r173336946","pull_request_url":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/comments/173336946"},"html":{"href":"https://github.com/pandas-dev/pandas/pull/20016#discussion_r173336946"},"pull_request":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016"}}},"pull_request":{"url":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016","id":173214454,"html_url":"https://github.com/pandas-dev/pandas/pull/20016","diff_url":"https://github.com/pandas-dev/pandas/pull/20016.diff","patch_url":"https://github.com/pandas-dev/pandas/pull/20016.patch","issue_url":"https://api.github.com/repos/pandas-dev/pandas/issues/20016","number":20016,"state":"open","locked":false,"title":"Shared doc guide","user":{"login":"TomAugspurger","id":1312546,"avatar_url":"https://avatars3.githubusercontent.com/u/1312546?v=4","gravatar_id":"","url":"https://api.github.com/users/TomAugspurger","html_url":"https://github.com/TomAugspurger","followers_url":"https://api.github.com/users/TomAugspurger/followers","following_url":"https://api.github.com/users/TomAugspurger/following{/other_user}","gists_url":"https://api.github.com/users/TomAugspurger/gists{/gist_id}","starred_url":"https://api.github.com/users/TomAugspurger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TomAugspurger/subscriptions","organizations_url":"https://api.github.com/users/TomAugspurger/orgs","repos_url":"https://api.github.com/users/TomAugspurger/repos","events_url":"https://api.github.com/users/TomAugspurger/events{/privacy}","received_events_url":"https://api.github.com/users/TomAugspurger/received_events","type":"User","site_admin":false},"body":"closes https://github.com/pandas-dev/pandas/issues/16446\r\n\r\nxref https://github.com/pandas-dev/pandas/issues/19932\r\n\r\ncc @jorisvandenbossche \r\n\r\nThe main change in best practices here is the recommendation is that `Appender` is only for appending. `Substitution` should be used for substituting values.\r\n\r\nSee the changes to `fillna` that this policy requires. Personally, I find the new way clearer than the old way.\r\n\r\n- We write the base template normally\r\n- I like `Appender(NDFrame.method.__doc__)` better than `Appender(_shared_docs['name'] % kwargs)`\r\n- I like `Substitution(**kwargs)` better than `%` formatting.\r\n\r\nThe downsides is that we don't have the template in a dictionary anymore and the docstring in `NDFrame` has to be the template, it can't have its variables substituted. I think that's OK.","created_at":"2018-03-06T16:41:54Z","updated_at":"2018-03-09T00:42:54Z","closed_at":null,"merged_at":null,"merge_commit_sha":"20ceb2678a6079c7bfabd6c90ddb546ff1693193","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[{"id":134699,"url":"https://api.github.com/repos/pandas-dev/pandas/labels/Docs","name":"Docs","color":"3465A4","default":false}],"milestone":{"url":"https://api.github.com/repos/pandas-dev/pandas/milestones/53","html_url":"https://github.com/pandas-dev/pandas/milestone/53","labels_url":"https://api.github.com/repos/pandas-dev/pandas/milestones/53/labels","id":2853937,"number":53,"title":"0.23.0","description":"after 0.22","creator":{"login":"jreback","id":953992,"avatar_url":"https://avatars2.githubusercontent.com/u/953992?v=4","gravatar_id":"","url":"https://api.github.com/users/jreback","html_url":"https://github.com/jreback","followers_url":"https://api.github.com/users/jreback/followers","following_url":"https://api.github.com/users/jreback/following{/other_user}","gists_url":"https://api.github.com/users/jreback/gists{/gist_id}","starred_url":"https://api.github.com/users/jreback/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jreback/subscriptions","organizations_url":"https://api.github.com/users/jreback/orgs","repos_url":"https://api.github.com/users/jreback/repos","events_url":"https://api.github.com/users/jreback/events{/privacy}","received_events_url":"https://api.github.com/users/jreback/received_events","type":"User","site_admin":false},"open_issues":144,"closed_issues":1105,"state":"open","created_at":"2017-10-20T10:17:09Z","updated_at":"2018-03-09T00:36:24Z","due_on":"2018-03-31T07:00:00Z","closed_at":null},"commits_url":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016/commits","review_comments_url":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016/comments","review_comment_url":"https://api.github.com/repos/pandas-dev/pandas/pulls/comments{/number}","comments_url":"https://api.github.com/repos/pandas-dev/pandas/issues/20016/comments","statuses_url":"https://api.github.com/repos/pandas-dev/pandas/statuses/0e43660d96d4f4d8f860643fc1271a603ad2390c","head":{"label":"TomAugspurger:shared-doc-guide","ref":"shared-doc-guide","sha":"0e43660d96d4f4d8f860643fc1271a603ad2390c","user":{"login":"TomAugspurger","id":1312546,"avatar_url":"https://avatars3.githubusercontent.com/u/1312546?v=4","gravatar_id":"","url":"https://api.github.com/users/TomAugspurger","html_url":"https://github.com/TomAugspurger","followers_url":"https://api.github.com/users/TomAugspurger/followers","following_url":"https://api.github.com/users/TomAugspurger/following{/other_user}","gists_url":"https://api.github.com/users/TomAugspurger/gists{/gist_id}","starred_url":"https://api.github.com/users/TomAugspurger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TomAugspurger/subscriptions","organizations_url":"https://api.github.com/users/TomAugspurger/orgs","repos_url":"https://api.github.com/users/TomAugspurger/repos","events_url":"https://api.github.com/users/TomAugspurger/events{/privacy}","received_events_url":"https://api.github.com/users/TomAugspurger/received_events","type":"User","site_admin":false},"repo":{"id":9450481,"name":"pandas","full_name":"TomAugspurger/pandas","owner":{"login":"TomAugspurger","id":1312546,"avatar_url":"https://avatars3.githubusercontent.com/u/1312546?v=4","gravatar_id":"","url":"https://api.github.com/users/TomAugspurger","html_url":"https://github.com/TomAugspurger","followers_url":"https://api.github.com/users/TomAugspurger/followers","following_url":"https://api.github.com/users/TomAugspurger/following{/other_user}","gists_url":"https://api.github.com/users/TomAugspurger/gists{/gist_id}","starred_url":"https://api.github.com/users/TomAugspurger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TomAugspurger/subscriptions","organizations_url":"https://api.github.com/users/TomAugspurger/orgs","repos_url":"https://api.github.com/users/TomAugspurger/repos","events_url":"https://api.github.com/users/TomAugspurger/events{/privacy}","received_events_url":"https://api.github.com/users/TomAugspurger/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/TomAugspurger/pandas","description":"Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more","fork":true,"url":"https://api.github.com/repos/TomAugspurger/pandas","forks_url":"https://api.github.com/repos/TomAugspurger/pandas/forks","keys_url":"https://api.github.com/repos/TomAugspurger/pandas/keys{/key_id}","collaborators_url":"https://api.github.com/repos/TomAugspurger/pandas/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/TomAugspurger/pandas/teams","hooks_url":"https://api.github.com/repos/TomAugspurger/pandas/hooks","issue_events_url":"https://api.github.com/repos/TomAugspurger/pandas/issues/events{/number}","events_url":"https://api.github.com/repos/TomAugspurger/pandas/events","assignees_url":"https://api.github.com/repos/TomAugspurger/pandas/assignees{/user}","branches_url":"https://api.github.com/repos/TomAugspurger/pandas/branches{/branch}","tags_url":"https://api.github.com/repos/TomAugspurger/pandas/tags","blobs_url":"https://api.github.com/repos/TomAugspurger/pandas/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/TomAugspurger/pandas/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/TomAugspurger/pandas/git/refs{/sha}","trees_url":"https://api.github.com/repos/TomAugspurger/pandas/git/trees{/sha}","statuses_url":"https://api.github.com/repos/TomAugspurger/pandas/statuses/{sha}","languages_url":"https://api.github.com/repos/TomAugspurger/pandas/languages","stargazers_url":"https://api.github.com/repos/TomAugspurger/pandas/stargazers","contributors_url":"https://api.github.com/repos/TomAugspurger/pandas/contributors","subscribers_url":"https://api.github.com/repos/TomAugspurger/pandas/subscribers","subscription_url":"https://api.github.com/repos/TomAugspurger/pandas/subscription","commits_url":"https://api.github.com/repos/TomAugspurger/pandas/commits{/sha}","git_commits_url":"https://api.github.com/repos/TomAugspurger/pandas/git/commits{/sha}","comments_url":"https://api.github.com/repos/TomAugspurger/pandas/comments{/number}","issue_comment_url":"https://api.github.com/repos/TomAugspurger/pandas/issues/comments{/number}","contents_url":"https://api.github.com/repos/TomAugspurger/pandas/contents/{+path}","compare_url":"https://api.github.com/repos/TomAugspurger/pandas/compare/{base}...{head}","merges_url":"https://api.github.com/repos/TomAugspurger/pandas/merges","archive_url":"https://api.github.com/repos/TomAugspurger/pandas/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/TomAugspurger/pandas/downloads","issues_url":"https://api.github.com/repos/TomAugspurger/pandas/issues{/number}","pulls_url":"https://api.github.com/repos/TomAugspurger/pandas/pulls{/number}","milestones_url":"https://api.github.com/repos/TomAugspurger/pandas/milestones{/number}","notifications_url":"https://api.github.com/repos/TomAugspurger/pandas/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/TomAugspurger/pandas/labels{/name}","releases_url":"https://api.github.com/repos/TomAugspurger/pandas/releases{/id}","deployments_url":"https://api.github.com/repos/TomAugspurger/pandas/deployments","created_at":"2013-04-15T14:23:40Z","updated_at":"2017-04-20T12:53:33Z","pushed_at":"2018-03-08T16:49:40Z","git_url":"git://github.com/TomAugspurger/pandas.git","ssh_url":"git@github.com:TomAugspurger/pandas.git","clone_url":"https://github.com/TomAugspurger/pandas.git","svn_url":"https://github.com/TomAugspurger/pandas","homepage":"http://pandas.pydata.org","size":120098,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"bsd-3-clause","name":"BSD 3-Clause \"New\" or \"Revised\" License","spdx_id":"BSD-3-Clause","url":"https://api.github.com/licenses/bsd-3-clause"},"forks":1,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"pandas-dev:master","ref":"master","sha":"e02f73787bfbd00ce2ad899542538dfad854eb01","user":{"login":"pandas-dev","id":21206976,"avatar_url":"https://avatars2.githubusercontent.com/u/21206976?v=4","gravatar_id":"","url":"https://api.github.com/users/pandas-dev","html_url":"https://github.com/pandas-dev","followers_url":"https://api.github.com/users/pandas-dev/followers","following_url":"https://api.github.com/users/pandas-dev/following{/other_user}","gists_url":"https://api.github.com/users/pandas-dev/gists{/gist_id}","starred_url":"https://api.github.com/users/pandas-dev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pandas-dev/subscriptions","organizations_url":"https://api.github.com/users/pandas-dev/orgs","repos_url":"https://api.github.com/users/pandas-dev/repos","events_url":"https://api.github.com/users/pandas-dev/events{/privacy}","received_events_url":"https://api.github.com/users/pandas-dev/received_events","type":"Organization","site_admin":false},"repo":{"id":858127,"name":"pandas","full_name":"pandas-dev/pandas","owner":{"login":"pandas-dev","id":21206976,"avatar_url":"https://avatars2.githubusercontent.com/u/21206976?v=4","gravatar_id":"","url":"https://api.github.com/users/pandas-dev","html_url":"https://github.com/pandas-dev","followers_url":"https://api.github.com/users/pandas-dev/followers","following_url":"https://api.github.com/users/pandas-dev/following{/other_user}","gists_url":"https://api.github.com/users/pandas-dev/gists{/gist_id}","starred_url":"https://api.github.com/users/pandas-dev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pandas-dev/subscriptions","organizations_url":"https://api.github.com/users/pandas-dev/orgs","repos_url":"https://api.github.com/users/pandas-dev/repos","events_url":"https://api.github.com/users/pandas-dev/events{/privacy}","received_events_url":"https://api.github.com/users/pandas-dev/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/pandas-dev/pandas","description":"Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more","fork":false,"url":"https://api.github.com/repos/pandas-dev/pandas","forks_url":"https://api.github.com/repos/pandas-dev/pandas/forks","keys_url":"https://api.github.com/repos/pandas-dev/pandas/keys{/key_id}","collaborators_url":"https://api.github.com/repos/pandas-dev/pandas/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/pandas-dev/pandas/teams","hooks_url":"https://api.github.com/repos/pandas-dev/pandas/hooks","issue_events_url":"https://api.github.com/repos/pandas-dev/pandas/issues/events{/number}","events_url":"https://api.github.com/repos/pandas-dev/pandas/events","assignees_url":"https://api.github.com/repos/pandas-dev/pandas/assignees{/user}","branches_url":"https://api.github.com/repos/pandas-dev/pandas/branches{/branch}","tags_url":"https://api.github.com/repos/pandas-dev/pandas/tags","blobs_url":"https://api.github.com/repos/pandas-dev/pandas/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/pandas-dev/pandas/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/pandas-dev/pandas/git/refs{/sha}","trees_url":"https://api.github.com/repos/pandas-dev/pandas/git/trees{/sha}","statuses_url":"https://api.github.com/repos/pandas-dev/pandas/statuses/{sha}","languages_url":"https://api.github.com/repos/pandas-dev/pandas/languages","stargazers_url":"https://api.github.com/repos/pandas-dev/pandas/stargazers","contributors_url":"https://api.github.com/repos/pandas-dev/pandas/contributors","subscribers_url":"https://api.github.com/repos/pandas-dev/pandas/subscribers","subscription_url":"https://api.github.com/repos/pandas-dev/pandas/subscription","commits_url":"https://api.github.com/repos/pandas-dev/pandas/commits{/sha}","git_commits_url":"https://api.github.com/repos/pandas-dev/pandas/git/commits{/sha}","comments_url":"https://api.github.com/repos/pandas-dev/pandas/comments{/number}","issue_comment_url":"https://api.github.com/repos/pandas-dev/pandas/issues/comments{/number}","contents_url":"https://api.github.com/repos/pandas-dev/pandas/contents/{+path}","compare_url":"https://api.github.com/repos/pandas-dev/pandas/compare/{base}...{head}","merges_url":"https://api.github.com/repos/pandas-dev/pandas/merges","archive_url":"https://api.github.com/repos/pandas-dev/pandas/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/pandas-dev/pandas/downloads","issues_url":"https://api.github.com/repos/pandas-dev/pandas/issues{/number}","pulls_url":"https://api.github.com/repos/pandas-dev/pandas/pulls{/number}","milestones_url":"https://api.github.com/repos/pandas-dev/pandas/milestones{/number}","notifications_url":"https://api.github.com/repos/pandas-dev/pandas/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/pandas-dev/pandas/labels{/name}","releases_url":"https://api.github.com/repos/pandas-dev/pandas/releases{/id}","deployments_url":"https://api.github.com/repos/pandas-dev/pandas/deployments","created_at":"2010-08-24T01:37:33Z","updated_at":"2018-03-09T00:29:20Z","pushed_at":"2018-03-09T00:36:24Z","git_url":"git://github.com/pandas-dev/pandas.git","ssh_url":"git@github.com:pandas-dev/pandas.git","clone_url":"https://github.com/pandas-dev/pandas.git","svn_url":"https://github.com/pandas-dev/pandas","homepage":"http://pandas.pydata.org","size":117894,"stargazers_count":13260,"watchers_count":13260,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":5145,"mirror_url":null,"archived":false,"open_issues_count":2388,"license":{"key":"bsd-3-clause","name":"BSD 3-Clause \"New\" or \"Revised\" License","spdx_id":"BSD-3-Clause","url":"https://api.github.com/licenses/bsd-3-clause"},"forks":5145,"open_issues":2388,"watchers":13260,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016"},"html":{"href":"https://github.com/pandas-dev/pandas/pull/20016"},"issue":{"href":"https://api.github.com/repos/pandas-dev/pandas/issues/20016"},"comments":{"href":"https://api.github.com/repos/pandas-dev/pandas/issues/20016/comments"},"review_comments":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016/comments"},"review_comment":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/pandas-dev/pandas/pulls/20016/commits"},"statuses":{"href":"https://api.github.com/repos/pandas-dev/pandas/statuses/0e43660d96d4f4d8f860643fc1271a603ad2390c"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"jreback"}}