{"action":"created","comment":{"url":"https://api.github.com/repos/pulp/pups/pulls/comments/110968651","pull_request_review_id":32178262,"id":110968651,"diff_hunk":"@@ -0,0 +1,121 @@\n+---\n+title: Docstring Style Conventions\n+author: Austin Macdonald\n+created: 28-Mar-2017\n+status: Accepted\n+---\n+\n+## Summary\n+\n+This PUP adopts Google's Python docstring style for Pulp 3+.\n+\n+## Motivation\n+\n+Pulp 2.Y docstrings use the standard Sphinx style, which is not very readable for humans. They\n+contain redundant words like `param` and they use an extra line for the `type` of every variable.\n+Most current Pulp developers find Google style docstrings to be more readable.\n+\n+## Docstring Style\n+\n+Docstrings should follow the conventions documented in the\n+[Comments section](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments)\n+of the Google Python Style Guide. Exceptions and clarifications will be explicitly stated in the\n+Pulp style guide.\n+\n+### Exceptions and Clarifications\n+\n+1. Modules should not include license information.\n+\n+2. The type of each `Arg` value should be included after the variable name in parentheses. The type\n+of each `Returns` value should be the first item on the line.\n+\n+3. Following the type of `Arg` and `Returns` values, there will be a colon and a single space\n+followed by the description. Additional spaces should not be used to align types and descriptions.\n+\n+4. `Fields` and `Relations` sections will be used when documenting fields on Django models.\n+The `Fields` section will be used for non-related fields on Model classes, the `Relations`\n+section will be used for related fields on Model classes.\n+\n+### Example\n+\n+    The first section is a summary, which should be restricted to a single line.\n+\n+    More detailed information follows the summary after a blank line. This section can be as many\n+    line as necessary.\n+\n+    Args:\n+        arg1 (str): The argument is visible, and its type is clearly indicated.\n+        much_longer_argument (str): Types and descriptions are not aligned.\n+    Returns:\n+        bool: The return value and type is very clearly visible.\n+\n+### Language\n+\n+\"Google style docstrings\" is the preferred way to refer to the style changes outlined here. It\n+should be noted that the phrase \"Napoleon style docstrings\" was originally used. Using the term\n+\"Napoleon\" is clear because it accepts docstrings of multiple styles.","path":"pup-0002.md","position":56,"original_position":56,"commit_id":"f22af9ff8d1a6f4d9f6daecdbb869bb5d94e0d00","original_commit_id":"f22af9ff8d1a6f4d9f6daecdbb869bb5d94e0d00","user":{"login":"mhrivnak","id":53091,"avatar_url":"https://avatars1.githubusercontent.com/u/53091?v=3","gravatar_id":"","url":"https://api.github.com/users/mhrivnak","html_url":"https://github.com/mhrivnak","followers_url":"https://api.github.com/users/mhrivnak/followers","following_url":"https://api.github.com/users/mhrivnak/following{/other_user}","gists_url":"https://api.github.com/users/mhrivnak/gists{/gist_id}","starred_url":"https://api.github.com/users/mhrivnak/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mhrivnak/subscriptions","organizations_url":"https://api.github.com/users/mhrivnak/orgs","repos_url":"https://api.github.com/users/mhrivnak/repos","events_url":"https://api.github.com/users/mhrivnak/events{/privacy}","received_events_url":"https://api.github.com/users/mhrivnak/received_events","type":"User","site_admin":false},"body":"Did you mean \"unclear\" or \"not clear\" ? Either way, perhaps \"ambiguous\" would be an improvement.","created_at":"2017-04-11T17:44:36Z","updated_at":"2017-04-11T17:44:36Z","html_url":"https://github.com/pulp/pups/pull/2#discussion_r110968651","pull_request_url":"https://api.github.com/repos/pulp/pups/pulls/2","_links":{"self":{"href":"https://api.github.com/repos/pulp/pups/pulls/comments/110968651"},"html":{"href":"https://github.com/pulp/pups/pull/2#discussion_r110968651"},"pull_request":{"href":"https://api.github.com/repos/pulp/pups/pulls/2"}}},"pull_request":{"url":"https://api.github.com/repos/pulp/pups/pulls/2","id":113010232,"html_url":"https://github.com/pulp/pups/pull/2","diff_url":"https://github.com/pulp/pups/pull/2.diff","patch_url":"https://github.com/pulp/pups/pull/2.patch","issue_url":"https://api.github.com/repos/pulp/pups/issues/2","number":2,"state":"open","locked":false,"title":"Add PUP for the use of google style docstrings","user":{"login":"asmacdo","id":1028657,"avatar_url":"https://avatars2.githubusercontent.com/u/1028657?v=3","gravatar_id":"","url":"https://api.github.com/users/asmacdo","html_url":"https://github.com/asmacdo","followers_url":"https://api.github.com/users/asmacdo/followers","following_url":"https://api.github.com/users/asmacdo/following{/other_user}","gists_url":"https://api.github.com/users/asmacdo/gists{/gist_id}","starred_url":"https://api.github.com/users/asmacdo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/asmacdo/subscriptions","organizations_url":"https://api.github.com/users/asmacdo/orgs","repos_url":"https://api.github.com/users/asmacdo/repos","events_url":"https://api.github.com/users/asmacdo/events{/privacy}","received_events_url":"https://api.github.com/users/asmacdo/received_events","type":"User","site_admin":false},"body":"Please add your comments here or on as a reply to the announcement on pulp-dev. The comment and voting period will end on ~Monday April 10 at 9pm UTC~ [April 12 at 9pm UTC](http://bit.ly/2oXOREo). \r\nhttps://pulp.plan.io/issues/2347","created_at":"2017-03-28T16:16:54Z","updated_at":"2017-04-11T17:44:36Z","closed_at":null,"merged_at":null,"merge_commit_sha":"eb9e4a8e61a297ec0462d1da73f4297d552fbda9","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/pulp/pups/pulls/2/commits","review_comments_url":"https://api.github.com/repos/pulp/pups/pulls/2/comments","review_comment_url":"https://api.github.com/repos/pulp/pups/pulls/comments{/number}","comments_url":"https://api.github.com/repos/pulp/pups/issues/2/comments","statuses_url":"https://api.github.com/repos/pulp/pups/statuses/f22af9ff8d1a6f4d9f6daecdbb869bb5d94e0d00","head":{"label":"asmacdo:google-docstrings","ref":"google-docstrings","sha":"f22af9ff8d1a6f4d9f6daecdbb869bb5d94e0d00","user":{"login":"asmacdo","id":1028657,"avatar_url":"https://avatars2.githubusercontent.com/u/1028657?v=3","gravatar_id":"","url":"https://api.github.com/users/asmacdo","html_url":"https://github.com/asmacdo","followers_url":"https://api.github.com/users/asmacdo/followers","following_url":"https://api.github.com/users/asmacdo/following{/other_user}","gists_url":"https://api.github.com/users/asmacdo/gists{/gist_id}","starred_url":"https://api.github.com/users/asmacdo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/asmacdo/subscriptions","organizations_url":"https://api.github.com/users/asmacdo/orgs","repos_url":"https://api.github.com/users/asmacdo/repos","events_url":"https://api.github.com/users/asmacdo/events{/privacy}","received_events_url":"https://api.github.com/users/asmacdo/received_events","type":"User","site_admin":false},"repo":{"id":86374915,"name":"pups","full_name":"asmacdo/pups","owner":{"login":"asmacdo","id":1028657,"avatar_url":"https://avatars2.githubusercontent.com/u/1028657?v=3","gravatar_id":"","url":"https://api.github.com/users/asmacdo","html_url":"https://github.com/asmacdo","followers_url":"https://api.github.com/users/asmacdo/followers","following_url":"https://api.github.com/users/asmacdo/following{/other_user}","gists_url":"https://api.github.com/users/asmacdo/gists{/gist_id}","starred_url":"https://api.github.com/users/asmacdo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/asmacdo/subscriptions","organizations_url":"https://api.github.com/users/asmacdo/orgs","repos_url":"https://api.github.com/users/asmacdo/repos","events_url":"https://api.github.com/users/asmacdo/events{/privacy}","received_events_url":"https://api.github.com/users/asmacdo/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/asmacdo/pups","description":"Pulp Update Proposal","fork":true,"url":"https://api.github.com/repos/asmacdo/pups","forks_url":"https://api.github.com/repos/asmacdo/pups/forks","keys_url":"https://api.github.com/repos/asmacdo/pups/keys{/key_id}","collaborators_url":"https://api.github.com/repos/asmacdo/pups/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/asmacdo/pups/teams","hooks_url":"https://api.github.com/repos/asmacdo/pups/hooks","issue_events_url":"https://api.github.com/repos/asmacdo/pups/issues/events{/number}","events_url":"https://api.github.com/repos/asmacdo/pups/events","assignees_url":"https://api.github.com/repos/asmacdo/pups/assignees{/user}","branches_url":"https://api.github.com/repos/asmacdo/pups/branches{/branch}","tags_url":"https://api.github.com/repos/asmacdo/pups/tags","blobs_url":"https://api.github.com/repos/asmacdo/pups/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/asmacdo/pups/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/asmacdo/pups/git/refs{/sha}","trees_url":"https://api.github.com/repos/asmacdo/pups/git/trees{/sha}","statuses_url":"https://api.github.com/repos/asmacdo/pups/statuses/{sha}","languages_url":"https://api.github.com/repos/asmacdo/pups/languages","stargazers_url":"https://api.github.com/repos/asmacdo/pups/stargazers","contributors_url":"https://api.github.com/repos/asmacdo/pups/contributors","subscribers_url":"https://api.github.com/repos/asmacdo/pups/subscribers","subscription_url":"https://api.github.com/repos/asmacdo/pups/subscription","commits_url":"https://api.github.com/repos/asmacdo/pups/commits{/sha}","git_commits_url":"https://api.github.com/repos/asmacdo/pups/git/commits{/sha}","comments_url":"https://api.github.com/repos/asmacdo/pups/comments{/number}","issue_comment_url":"https://api.github.com/repos/asmacdo/pups/issues/comments{/number}","contents_url":"https://api.github.com/repos/asmacdo/pups/contents/{+path}","compare_url":"https://api.github.com/repos/asmacdo/pups/compare/{base}...{head}","merges_url":"https://api.github.com/repos/asmacdo/pups/merges","archive_url":"https://api.github.com/repos/asmacdo/pups/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/asmacdo/pups/downloads","issues_url":"https://api.github.com/repos/asmacdo/pups/issues{/number}","pulls_url":"https://api.github.com/repos/asmacdo/pups/pulls{/number}","milestones_url":"https://api.github.com/repos/asmacdo/pups/milestones{/number}","notifications_url":"https://api.github.com/repos/asmacdo/pups/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/asmacdo/pups/labels{/name}","releases_url":"https://api.github.com/repos/asmacdo/pups/releases{/id}","deployments_url":"https://api.github.com/repos/asmacdo/pups/deployments","created_at":"2017-03-27T19:20:32Z","updated_at":"2017-03-10T23:53:40Z","pushed_at":"2017-04-11T17:35:30Z","git_url":"git://github.com/asmacdo/pups.git","ssh_url":"git@github.com:asmacdo/pups.git","clone_url":"https://github.com/asmacdo/pups.git","svn_url":"https://github.com/asmacdo/pups","homepage":"http://pulpproject.org","size":20,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"pulp:master","ref":"master","sha":"159a3691c340514e986bccbbdc8ad74b49129c27","user":{"login":"pulp","id":2103606,"avatar_url":"https://avatars2.githubusercontent.com/u/2103606?v=3","gravatar_id":"","url":"https://api.github.com/users/pulp","html_url":"https://github.com/pulp","followers_url":"https://api.github.com/users/pulp/followers","following_url":"https://api.github.com/users/pulp/following{/other_user}","gists_url":"https://api.github.com/users/pulp/gists{/gist_id}","starred_url":"https://api.github.com/users/pulp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pulp/subscriptions","organizations_url":"https://api.github.com/users/pulp/orgs","repos_url":"https://api.github.com/users/pulp/repos","events_url":"https://api.github.com/users/pulp/events{/privacy}","received_events_url":"https://api.github.com/users/pulp/received_events","type":"Organization","site_admin":false},"repo":{"id":84610215,"name":"pups","full_name":"pulp/pups","owner":{"login":"pulp","id":2103606,"avatar_url":"https://avatars2.githubusercontent.com/u/2103606?v=3","gravatar_id":"","url":"https://api.github.com/users/pulp","html_url":"https://github.com/pulp","followers_url":"https://api.github.com/users/pulp/followers","following_url":"https://api.github.com/users/pulp/following{/other_user}","gists_url":"https://api.github.com/users/pulp/gists{/gist_id}","starred_url":"https://api.github.com/users/pulp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pulp/subscriptions","organizations_url":"https://api.github.com/users/pulp/orgs","repos_url":"https://api.github.com/users/pulp/repos","events_url":"https://api.github.com/users/pulp/events{/privacy}","received_events_url":"https://api.github.com/users/pulp/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/pulp/pups","description":"Pulp Update Proposal","fork":false,"url":"https://api.github.com/repos/pulp/pups","forks_url":"https://api.github.com/repos/pulp/pups/forks","keys_url":"https://api.github.com/repos/pulp/pups/keys{/key_id}","collaborators_url":"https://api.github.com/repos/pulp/pups/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/pulp/pups/teams","hooks_url":"https://api.github.com/repos/pulp/pups/hooks","issue_events_url":"https://api.github.com/repos/pulp/pups/issues/events{/number}","events_url":"https://api.github.com/repos/pulp/pups/events","assignees_url":"https://api.github.com/repos/pulp/pups/assignees{/user}","branches_url":"https://api.github.com/repos/pulp/pups/branches{/branch}","tags_url":"https://api.github.com/repos/pulp/pups/tags","blobs_url":"https://api.github.com/repos/pulp/pups/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/pulp/pups/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/pulp/pups/git/refs{/sha}","trees_url":"https://api.github.com/repos/pulp/pups/git/trees{/sha}","statuses_url":"https://api.github.com/repos/pulp/pups/statuses/{sha}","languages_url":"https://api.github.com/repos/pulp/pups/languages","stargazers_url":"https://api.github.com/repos/pulp/pups/stargazers","contributors_url":"https://api.github.com/repos/pulp/pups/contributors","subscribers_url":"https://api.github.com/repos/pulp/pups/subscribers","subscription_url":"https://api.github.com/repos/pulp/pups/subscription","commits_url":"https://api.github.com/repos/pulp/pups/commits{/sha}","git_commits_url":"https://api.github.com/repos/pulp/pups/git/commits{/sha}","comments_url":"https://api.github.com/repos/pulp/pups/comments{/number}","issue_comment_url":"https://api.github.com/repos/pulp/pups/issues/comments{/number}","contents_url":"https://api.github.com/repos/pulp/pups/contents/{+path}","compare_url":"https://api.github.com/repos/pulp/pups/compare/{base}...{head}","merges_url":"https://api.github.com/repos/pulp/pups/merges","archive_url":"https://api.github.com/repos/pulp/pups/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/pulp/pups/downloads","issues_url":"https://api.github.com/repos/pulp/pups/issues{/number}","pulls_url":"https://api.github.com/repos/pulp/pups/pulls{/number}","milestones_url":"https://api.github.com/repos/pulp/pups/milestones{/number}","notifications_url":"https://api.github.com/repos/pulp/pups/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/pulp/pups/labels{/name}","releases_url":"https://api.github.com/repos/pulp/pups/releases{/id}","deployments_url":"https://api.github.com/repos/pulp/pups/deployments","created_at":"2017-03-10T23:48:14Z","updated_at":"2017-03-10T23:53:40Z","pushed_at":"2017-04-11T17:35:31Z","git_url":"git://github.com/pulp/pups.git","ssh_url":"git@github.com:pulp/pups.git","clone_url":"https://github.com/pulp/pups.git","svn_url":"https://github.com/pulp/pups","homepage":"http://pulpproject.org","size":17,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":3,"forks":3,"open_issues":3,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/pulp/pups/pulls/2"},"html":{"href":"https://github.com/pulp/pups/pull/2"},"issue":{"href":"https://api.github.com/repos/pulp/pups/issues/2"},"comments":{"href":"https://api.github.com/repos/pulp/pups/issues/2/comments"},"review_comments":{"href":"https://api.github.com/repos/pulp/pups/pulls/2/comments"},"review_comment":{"href":"https://api.github.com/repos/pulp/pups/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/pulp/pups/pulls/2/commits"},"statuses":{"href":"https://api.github.com/repos/pulp/pups/statuses/f22af9ff8d1a6f4d9f6daecdbb869bb5d94e0d00"}}}}
{"actor":{"display_login":"mhrivnak"}}