Services.repos.Repo doc

And typos

3 files changed, 133 insertions, 29 deletions

diff --git a/pygithub3/services/base.py b/pygithub3/services/base.py
index fced575..d50ceb7 100644
--- a/pygithub3/services/base.py
+++ b/pygithub3/services/base.py
@@ -26,8 +26,8 @@ class Service(object):
     If you include ``login``, ``password`` and ``token`` in config; Oauth has
     precedence
 
-    Some API requests need ``user`` and/or ``repo`` arguments (e.g repos
-    service).
+    Some API requests need ``user`` and/or ``repo`` arguments (e.g
+    :ref:`repos service <config precedence>`).
     You can configure the default value here to avoid repeating
 
     Some API requests return multiple resources with pagination. You can
diff --git a/pygithub3/services/repos.py b/pygithub3/services/repos.py
index 3643633..b4cf43c 100644
--- a/pygithub3/services/repos.py
+++ b/pygithub3/services/repos.py
@@ -184,22 +184,96 @@ class Repo(Service):
         super(Repo, self).__init__(**config)
 
     def list(self, user=None, type='all'):
+        """ Get user's repositories
+
+        :param str user: Username
+        :param str type: Filter by type (optional). See `github repo doc`_
+        :returns: A :doc:`result`
+
+        If you call it without user and you are authenticated, get the
+        authenticated user's repositories
+
+        .. warning::
+
+            If you aren't authenticated and call without user, it returns 403
+
+        ::
+
+            repo_service.list('copitux', type='owner')
+            repo_service.list(type='private')
+        """
         request = self.make_request('repos.list', user=user)
         return self._get_result(request, type=type)
 
     def list_by_org(self, org, type='all'):
+        """ Get organization's repositories
+
+        :param str org: Organization name
+        :param str type: Filter by type (optional). See `github repo doc`_
+        :returns: A :doc:`result`
+
+        ::
+
+            repo_service.list_by_org('myorganization', type='member')
+        """
         request = self.make_request('repos.list_by_org', org=org)
         return self._get_result(request, type=type)
 
     def create(self, data, in_org=None):
+        """ Create a new repository
+
+        :param dict data: Input. See `github repo doc`_
+        :param str in_org: Organization where create the repository (optional)
+
+        .. warning::
+
+            You must be authenticated
+
+            If you use ``in_org`` arg, the authenticated user must be a member
+            of <in_org>
+
+        ::
+
+            repo_service.create(dict(name='new_repo', description='desc'))
+            repo_service.create(dict(name='new_repo_in_org', team_id=2300),
+                in_org='myorganization')
+        """
         request = self.make_request('repos.create', org=in_org, body=data)
         return self._post(request)
 
     def get(self, user=None, repo=None):
+        """ Get a single repo
+
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.get', user=user, repo=repo)
         return self._get(request)
 
     def update(self, data, user=None, repo=None):
+        """ Update a single repository
+
+        :param dict data: Input. See `github repo doc`_
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        .. warning::
+
+            You must be authenticated
+
+        ::
+
+            repo_service.update(dict(has_issues=True), user='octocat',
+                repo='oct_repo')
+        """
         request = self.make_request('repos.update', body=data,
             user=user, repo=repo)
         return self._patch(request)
@@ -210,25 +284,77 @@ class Repo(Service):
         return self._get_result(request, **kwargs)
 
     def list_contributors(self, user=None, repo=None):
+        """ Get repository's contributors
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         return self.__list_contributors(user, repo)
 
     def list_contributors_with_anonymous(self, user=None, repo=None):
+        """ Like :attr:`~pygithub3.services.repos.Repo.list_contributors` plus
+        anonymous """
         return self.__list_contributors(user, repo, anom=True)
 
     def list_languages(self, user=None, repo=None):
+        """ Get repository's languages
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.list_languages',
             user=user, repo=repo)
         return self._get(request)
 
     def list_teams(self, user=None, repo=None):
+        """ Get repository's teams
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.list_teams', user=user, repo=repo)
         return self._get_result(request)
 
     def list_tags(self, user=None, repo=None):
+        """ Get repository's tags
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.list_tags', user=user, repo=repo)
         return self._get_result(request)
 
     def list_branches(self, user=None, repo=None):
+        """ Get repository's branches
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.list_branches',
             user=user, repo=repo)
         return self._get_result(request)
diff --git a/pygithub3/services/users.py b/pygithub3/services/users.py
index 8c436e6..0c8c7aa 100644
--- a/pygithub3/services/users.py
+++ b/pygithub3/services/users.py
@@ -15,7 +15,7 @@ class Keys(Service):
     def list(self):
         """ Get public keys
 
-        It returns a :doc:`result`
+        :returns: A :doc:`result`
         """
         request = self.make_request('users.keys.list')
         return self._get_result(request)
@@ -24,10 +24,6 @@ class Keys(Service):
         """ Get a public key
 
         :param int key_id: Key id
-
-        ::
-
-            key_service.get(42)
         """
         request = self.make_request('users.keys.get',
             key_id=key_id)
@@ -64,10 +60,6 @@ class Keys(Service):
         """ Delete a public key
 
         :param int key_id: Key id
-
-        ::
-
-            key_service.delete(42)
         """
         request = self.make_request('users.keys.delete',
             key_id=key_id)
@@ -83,8 +75,7 @@ class Followers(Service):
         """ Get user's followers
 
         :param str user: Username
-
-        It returns a :doc:`result`
+        :returns: A :doc:`result`
 
         If you call it without user and you are authenticated, get the
         authenticated user's followers
@@ -105,8 +96,7 @@ class Followers(Service):
         """ Get who a user is following
 
         :param str user: Username
-
-        It returns a :doc:`result`
+        :returns: A :doc:`result`
 
         If you call it without user and you are authenticated, get the
         authenticated user's followings
@@ -127,10 +117,6 @@ class Followers(Service):
         """ Check if you are following a user
 
         :param str user: Username
-
-        ::
-
-            followers_service.is_following('octocat')
         """
         request = self.make_request('users.followers.isfollowing', user=user)
         return self._bool(request)
@@ -143,10 +129,6 @@ class Followers(Service):
         .. warning::
 
             You must be authenticated
-
-        ::
-
-            followers_service.follow('octocat')
         """
         request = self.make_request('users.followers.follow', user=user)
         self._put(request)
@@ -159,10 +141,6 @@ class Followers(Service):
         .. warning::
 
             You must be authenticated
-
-        ::
-
-            followers_service.unfollow('octocat')
         """
         request = self.make_request('users.followers.unfollow', user=user)
         self._delete(request)
@@ -179,7 +157,7 @@ class Emails(Service):
     def list(self):
         """ Get user's emails
 
-        It returns a :doc:`result`
+        :returns: A :doc:`result`
         """
         request = self.make_request('users.emails.list')
         return self._get_result(request)
@@ -191,7 +169,7 @@ class Emails(Service):
 
         .. note::
 
-            It reject non-valid emails
+            It rejects non-valid emails
 
         ::