Complete services.repos doc

Also add Mimetypes doc

7 files changed, 224 insertions, 24 deletions

diff --git a/pygithub3/services/repos/__init__.py b/pygithub3/services/repos/__init__.py
index e1ed1d8..484dd49 100644
--- a/pygithub3/services/repos/__init__.py
+++ b/pygithub3/services/repos/__init__.py
@@ -33,7 +33,6 @@ class Repos(Service):
         authenticated user's repositories
 
         .. warning::
-
             If you aren't authenticated and call without user, it returns 403
 
         ::
@@ -87,7 +86,6 @@ class Repos(Service):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.get', user=user, repo=repo)
@@ -101,11 +99,9 @@ class Repos(Service):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
 
         .. warning::
-
             You must be authenticated
 
         ::
@@ -130,7 +126,6 @@ class Repos(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         return self.__list_contributors(user, repo)
@@ -148,7 +143,6 @@ class Repos(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.list_languages',
@@ -163,7 +157,6 @@ class Repos(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.list_teams', user=user, repo=repo)
@@ -177,7 +170,6 @@ class Repos(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.list_tags', user=user, repo=repo)
@@ -191,7 +183,6 @@ class Repos(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.list_branches',
diff --git a/pygithub3/services/repos/collaborators.py b/pygithub3/services/repos/collaborators.py
index 5f0703a..f80a406 100644
--- a/pygithub3/services/repos/collaborators.py
+++ b/pygithub3/services/repos/collaborators.py
@@ -16,7 +16,6 @@ class Collaborators(Service):
         :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.collaborators.list',
@@ -31,11 +30,9 @@ class Collaborators(Service):
         :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',
@@ -50,7 +47,6 @@ class Collaborators(Service):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.collaborators.is_collaborator',
@@ -65,11 +61,9 @@ class Collaborators(Service):
         :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',
diff --git a/pygithub3/services/repos/commits.py b/pygithub3/services/repos/commits.py
index 23e6842..8eec3e7 100644
--- a/pygithub3/services/repos/commits.py
+++ b/pygithub3/services/repos/commits.py
@@ -25,7 +25,6 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.commits.get',
@@ -38,9 +37,9 @@ class Commits(Service, MimeTypeMixin):
         :param str sha: Commit's sha
         :param str user: Username
         :param str repo: Repository
+        :returns: A :doc:`result`
 
         .. note::
-
             Remember :ref:`config precedence`
 
         If you call it without ``sha``, get all commit's comments of a
@@ -64,9 +63,11 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
 
+        .. warning::
+            You must be authenticated
+
         ::
 
             data = {
@@ -91,7 +92,6 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.commits.get_comment',
@@ -107,9 +107,11 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
 
+        .. warning::
+            You must be authenticated
+
         ::
 
             commits_service.update_comment(dict(body='nice change'), 42,
@@ -128,7 +130,6 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
 
         ::
@@ -148,7 +149,6 @@ class Commits(Service, MimeTypeMixin):
         :param str repo: Repository
 
         .. note::
-
             Remember :ref:`config precedence`
         """
         request = self.make_request('repos.commits.delete_comment',
diff --git a/pygithub3/services/repos/downloads.py b/pygithub3/services/repos/downloads.py
index c455021..47c7785 100644
--- a/pygithub3/services/repos/downloads.py
+++ b/pygithub3/services/repos/downloads.py
@@ -7,24 +7,71 @@ from . import Service
 
 
 class Downloads(Service):
+    """ Consume `Downloads API
+    <http://developer.github.com/v3/repos/downloads>`_ """
 
     def list(self, user=None, repo=None):
+        """ Get repository's downloads
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.downloads.list',
             user=user, repo=repo)
         return self._get_result(request)
 
     def get(self, id, user=None, repo=None):
+        """ Get a single download
+
+        :param int id: Download id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.downloads.get',
             id=id, user=user, repo=repo)
         return self._get(request)
 
     def create(self, data, user=None, repo=None):
+        """ Create a new download
+
+        :param dict data: Input. See `github downloads doc`_
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        It is a two step process. After you create the download, you must
+        call the ``upload`` function of ``Download`` resource with
+        ``file_path``
+
+        .. warning::
+            In `alpha` state
+
+        ::
+
+            # Step 1
+            download = downloads_service.create(
+                dict(name='new_download', size=1130),
+                user='octocat', repo='oct_repo')
+
+            # Step 2
+            download.upload('/home/user/file.ext')
+        """
         request = self.make_request('repos.downloads.create',
             body=data, user=user, repo=repo)
         download = self._post(request)
 
         # TODO: improve it. e.g Manage all with file desc
         def upload(file_path):
+            """ """
             body = download.ball_to_upload()
             body['file'] = (file_path, open(file_path, 'rb'))
             return requests.post(download.s3_url, files=body)
@@ -32,7 +79,16 @@ class Downloads(Service):
         download.upload = upload
         return download
 
-    def delete(self, id=id, user=None, repo=None):
+    def delete(self, id, user=None, repo=None):
+        """ Delete a download
+
+        :param int id: Download id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.downloads.delete',
             id=id, user=user, repo=repo)
         self._delete(request)
diff --git a/pygithub3/services/repos/forks.py b/pygithub3/services/repos/forks.py
index 09f23c5..df51347 100644
--- a/pygithub3/services/repos/forks.py
+++ b/pygithub3/services/repos/forks.py
@@ -5,13 +5,48 @@ from . import Service
 
 
 class Forks(Service):
+    """ Consume `Forks API
+    <http://developer.github.com/v3/repos/forks>`_ """
 
     def list(self, user=None, repo=None, sort='newest'):
+        """ Get repository's forks
+
+        :param str user: Username
+        :param str repo: Repository
+        :param str sort: Order resources (optional). See `github forks doc`_
+        :returns: A :doc:`result`
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        ::
+
+            forks_service.list(user='octocat', repo='oct_repo', sort='oldest')
+        """
         request = self.make_request('repos.forks.list', user=user, repo=repo)
         return self._get_result(request, sort=sort)
 
     def create(self, user=None, repo=None, org=None):
+        """ Fork a repository
+
+        :param str user: Username
+        :param str repo: Repository
+        :param str org: Organization name (optional)
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated
+
+        If you call it with ``org``, the repository will be forked into this
+        organization.
+        ::
+
+            forks_service.create(user='octocat', repo='oct_repo')
+            forks_service.create(user='octocat', repo='oct_repo',
+                org='myorganization'
+        """
         request = self.make_request('repos.forks.create', user=user, repo=repo)
-        #org = {'org': org} if org else {}
         org = org and {'org': org} or {}
         return self._post(request, **org)
diff --git a/pygithub3/services/repos/keys.py b/pygithub3/services/repos/keys.py
index 24a7cb3..1ade8a1 100644
--- a/pygithub3/services/repos/keys.py
+++ b/pygithub3/services/repos/keys.py
@@ -5,27 +5,91 @@ from . import Service
 
 
 class Keys(Service):
+    """ Consume `Deploy keys API
+    <http://developer.github.com/v3/repos/keys>`_ """
 
     def list(self, user=None, repo=None):
+        """ Get repository's keys
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.keys.list', user=user, repo=repo)
         return self._get_result(request)
 
     def get(self, id, user=None, repo=None):
+        """ Get a single repository key
+
+        :param int id: Repository key id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.keys.get',
             id=id, user=user, repo=repo)
         return self._get(request)
 
     def create(self, data, user=None, repo=None):
+        """ Create a repository key
+
+        :param dict data: Input. See `github keys doc`_
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated and have perms in the repository
+
+        ::
+
+            keys_service.create(dict(title='new key', key='ssh-rsa AAA...'),
+                user='octocat', repo='oct_repo')
+        """
         request = self.make_request('repos.keys.create',
             body=data, user=user, repo=repo)
         return self._post(request)
 
     def update(self, id, data, user=None, repo=None):
+        """ Update a repository key
+
+        :param int id: Repository key id
+        :param dict data: Input. See `github keys doc`_
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated and have perms in the repository
+
+        ::
+
+            keys_service.update(42, dict(title='new title'),
+                user='octocat', repo='oct_repo')
+        """
         request = self.make_request('repos.keys.update',
             id=id, body=data, user=user, repo=repo)
         return self._patch(request)
 
     def delete(self, id, user=None, repo=None):
+        """ Delete a repository key
+
+        :param int id: Repository key id
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.keys.delete',
             id=id, user=user, repo=repo)
         self._delete(request)
diff --git a/pygithub3/services/repos/watchers.py b/pygithub3/services/repos/watchers.py
index 8598590..7bcede5 100644
--- a/pygithub3/services/repos/watchers.py
+++ b/pygithub3/services/repos/watchers.py
@@ -5,27 +5,87 @@ from . import Service
 
 
 class Watchers(Service):
+    """ Consume `Watching API
+    <http://developer.github.com/v3/repos/watching>`_ """
 
     def list(self, user=None, repo=None):
+        """ Get repository's watchers
+
+        :param str user: Username
+        :param str repo: Repository
+        :returns: A :doc:`result`
+
+        .. note::
+            Remember :ref:`config precedence`
+        """
         request = self.make_request('repos.watchers.list',
             user=user, repo=repo)
         return self._get_result(request)
 
     def list_repos(self, user=None):
+        """ Get repositories being watched by a user
+
+        :param str user: Username
+        :returns: A :doc:`result`
+
+        If you call it without user and you are authenticated, get the
+        repositories being watched by the authenticated user.
+
+        .. warning::
+            If you aren't authenticated and call without user, it returns 403
+
+        ::
+
+            watchers_service.list_repos('copitux')
+            watchers_service.list_repos()
+        """
         request = self.make_request('repos.watchers.list_repos', user=user)
         return self._get_result(request)
 
     def is_watching(self, user=None, repo=None):
+        """ Check if authenticated user is watching a repository
+
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated
+        """
         request = self.make_request('repos.watchers.is_watching',
             user=user, repo=repo)
         return self._bool(request)
 
     def watch(self, user=None, repo=None):
+        """ Watch a repository
+
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated
+        """
         request = self.make_request('repos.watchers.watch',
             user=user, repo=repo)
         self._put(request)
 
     def unwatch(self, user=None, repo=None):
+        """ Stop watching a repository
+
+        :param str user: Username
+        :param str repo: Repository
+
+        .. note::
+            Remember :ref:`config precedence`
+
+        .. warning::
+            You must be authenticated
+        """
         request = self.make_request('repos.watchers.unwatch',
             user=user, repo=repo)
         self._delete(request)