WIP on services.repos doc

+services.repos.collaborators doc
+services.repos.commits doc

3 files changed, 166 insertions, 8 deletions

diff --git a/pygithub3/services/repos/__init__.py b/pygithub3/services/repos/__init__.py
index 6e3627f..e1ed1d8 100644
--- a/pygithub3/services/repos/__init__.py
+++ b/pygithub3/services/repos/__init__.py
@@ -26,7 +26,7 @@ class Repos(Service):
         """ Get user's repositories
 
         :param str user: Username
-        :param str type: Filter by type (optional). See `github repo doc`_
+        :param str type: Filter by type (optional). See `github repos doc`_
         :returns: A :doc:`result`
 
         If you call it without user and you are authenticated, get the
@@ -48,7 +48,7 @@ class Repos(Service):
         """ Get organization's repositories
 
         :param str org: Organization name
-        :param str type: Filter by type (optional). See `github repo doc`_
+        :param str type: Filter by type (optional). See `github repos doc`_
         :returns: A :doc:`result`
 
         ::
@@ -61,7 +61,7 @@ class Repos(Service):
     def create(self, data, in_org=None):
         """ Create a new repository
 
-        :param dict data: Input. See `github repo doc`_
+        :param dict data: Input. See `github repos doc`_
         :param str in_org: Organization where create the repository (optional)
 
         .. warning::
@@ -96,7 +96,7 @@ class Repos(Service):
     def update(self, data, user=None, repo=None):
         """ Update a single repository
 
-        :param dict data: Input. See `github repo doc`_
+        :param dict data: Input. See `github repos doc`_
         :param str user: Username
         :param str repo: Repository
 
diff --git a/pygithub3/services/repos/collaborators.py b/pygithub3/services/repos/collaborators.py
index 3bc4c9d..5f0703a 100644
--- a/pygithub3/services/repos/collaborators.py
+++ b/pygithub3/services/repos/collaborators.py
@@ -5,23 +5,73 @@ from . import Service
 
 
 class Collaborators(Service):
+    """ Consume `Repo Collaborators API
+    <http://developer.github.com/v3/repos/collaborators>`_ """
 
     def list(self, user=None, repo=None):
+        """ Get repository's collaborators
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.collaborators.list',
             user=user, repo=repo)
         return self._get_result(request)
 
     def add(self, collaborator, user=None, repo=None):
+        """ Add collaborator to a repository
+
+        :param str collaborator: Collaborator's username
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        .. warning::
+
+            You must be authenticated and have perms in repository
+        """
         request = self.make_request('repos.collaborators.add',
             collaborator=collaborator, user=user, repo=repo)
         return self._put(request)
 
     def is_collaborator(self, collaborator, user=None, repo=None):
+        """ Check if a user is collaborator on repository
+
+        :param str collaborator: Collaborator's username
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.collaborators.is_collaborator',
             collaborator=collaborator, user=user, repo=repo)
         return self._bool(request)
 
     def delete(self, collaborator, user=None, repo=None):
+        """ Remove collaborator from repository
+
+        :param str collaborator: Collaborator's username
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        .. warning::
+
+            You must be authenticated and have perms in repository
+        """
         request = self.make_request('repos.collaborators.delete',
             collaborator=collaborator, user=user, repo=repo)
         self._delete(request)
diff --git a/pygithub3/services/repos/commits.py b/pygithub3/services/repos/commits.py
index 3d5abb6..23e6842 100644
--- a/pygithub3/services/repos/commits.py
+++ b/pygithub3/services/repos/commits.py
@@ -5,44 +5,152 @@ from . import Service, MimeTypeMixin
 
 
 class Commits(Service, MimeTypeMixin):
+    """ Consume `Commits API
+    <http://developer.github.com/v3/repos/commits>`_
 
-    """ TODO: Pagination structure differs from usual
-    def list(self, user=None, repo=None, sha='', path=''):
-        request = self.make_request('repos.commits.list', user=user, repo=repo)
-        return self._get_result(request, sha=sha, path=path)
+    .. note::
+        This service support :ref:`mimetypes` configuration
     """
 
+    #TODO: Pagination structure differs from usual
+    #def list(self, user=None, repo=None, sha='', path=''):
+        #request = self.make_request('repos.commits.list', user=user, repo=repo)
+        #return self._get_result(request, sha=sha, path=path)
+
     def get(self, sha, user=None, repo=None):
+        """ Get a single commit
+
+        :param str sha: Commit's sha
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.commits.get',
             sha=sha, user=user, repo=repo)
         return self._get(request)
 
     def list_comments(self, sha=None, user=None, repo=None):
+        """ Get commit's comments
+
+        :param str sha: Commit's sha
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        If you call it without ``sha``, get all commit's comments of a
+        repository
+        ::
+
+            commits_service.list_comments('6dcb09', user='octocat',
+                repo='oct_repo')
+            commits_service.list_comments(user='octocat', repo='oct_repo')
+        """
         request = self.make_request('repos.commits.list_comments',
             sha=sha, user=user, repo=repo)
         return self._get_result(request, **self._get_mimetype_as_header())
 
     def create_comment(self, data, sha, user=None, repo=None):
+        """ Create a commit comment
+
+        :param dict data: Input. See `github commits doc`_
+        :param str sha: Commit's sha
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        ::
+
+            data = {
+                "body": "Nice change",
+                "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
+                "line": 1,
+                "path": "file1.txt",
+                "position": 4
+            }
+            commits_service.create_comment(data, '6dcb09', user='octocat',
+                repo='oct_repo')
+        """
         request = self.make_request('repos.commits.create_comment',
             sha=sha, user=user, repo=repo, body=data)
         return self._post(request, **self._get_mimetype_as_header())
 
     def get_comment(self, cid, user=None, repo=None):
+        """ Get a single commit comment
+
+        :param int cid: Commit comment id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.commits.get_comment',
             comment_id=cid, user=user, repo=repo)
         return self._get(request, **self._get_mimetype_as_header())
 
     def update_comment(self, data, cid, user=None, repo=None):
+        """ Update a single commit comment
+
+        :param dict data: Input. See `github commits doc`_
+        :param int cid: Commit comment id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        ::
+
+            commits_service.update_comment(dict(body='nice change'), 42,
+                user='octocat', repo='oct_repo')
+        """
         request = self.make_request('repos.commits.update_comment',
             comment_id=cid, user=user, repo=repo, body=data)
         return self._patch(request, **self._get_mimetype_as_header())
 
     def compare(self, base, head, user=None, repo=None):
+        """ Compare two commits
+
+        :param str base: Base commit sha
+        :param str head: Head commit sha
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+
+        ::
+
+            commits_service.compare('6dcb09', 'master', user='octocat',
+                repo='oct_repo')
+        """
         request = self.make_request('repos.commits.compare',
             base=base, head=head, user=user, repo=repo)
         return self._get(request)
 
     def delete_comment(self, cid, user=None, repo=None):
+        """ Delete a single commit comment
+
+        :param int cid: Commit comment id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.commits.delete_comment',
             comment_id=cid, user=user, repo=repo)
         self._delete(request)