Init documentation

+core
+services.user
~services.repos

3 files changed, 227 insertions, 2 deletions

diff --git a/pygithub3/services/base.py b/pygithub3/services/base.py
index 21b22eb..fced575 100644
--- a/pygithub3/services/base.py
+++ b/pygithub3/services/base.py
@@ -8,6 +8,34 @@ from pygithub3.core.errors import NotFound
 
 
 class Service(object):
+    """
+    You can configure each service with this keyword variables:
+
+    :param str login: Username to authenticate
+    :param str password: Username to authenticate
+    :param str user: Default username in requests
+    :param str repo: Default repository in requests
+    :param str token: Token to OAuth
+    :param int per_page: Items in each page of multiple returns
+    :param str base_url: To support another github-related API (untested)
+    :param stream verbose: Stream to write debug logs
+
+    You can configure the **authentication** with BasicAuthentication (login
+    and password) and with `OAuth <http://developer.github.com/v3/oauth/>`_ (
+    token).
+    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).
+    You can configure the default value here to avoid repeating
+
+    Some API requests return multiple resources with pagination. You can
+    configure how many items has each page.
+
+    You can configure ``verbose`` logging like `requests library <http://docs.
+    python-requests.org/en/v0.10.6/user/advanced/#verbose-logging>`_
+    """
 
     def __init__(self, **config):
         self._client = Client(**config)
@@ -17,18 +45,35 @@ class Service(object):
         return self._client.user
 
     def set_user(self, user):
+        """ Set user
+
+        :param str user: Default username in requests
+        """
         self._client.user = user
 
     def get_repo(self):
         return self._client.repo
 
     def set_repo(self, repo):
+        """ Set repository
+
+        :param str repo: Default repository in requests
+        """
         self._client.repo = repo
 
     def set_credentials(self, login, password):
+        """ Set Basic Authentication
+
+        :param str login: Username to authenticate
+        :param str password: Username to authenticate
+        """
         self._client.set_credentials(login, password)
 
     def set_token(self, token):
+        """ Set OAuth token
+
+        :param str token: Token to OAuth
+        """
         self._client.set_token(token)
 
     def make_request(self, request, **kwargs):
@@ -90,6 +135,16 @@ class Service(object):
 
 
 class MimeTypeMixin(object):
+    """
+    Mimetype support to Services that inherit this Mixin
+
+    Adds 4 public functions to service:
+
+        1. set_raw_mimetype
+        2. set_text_mimetype
+        3. set_html_mimetype
+        4. set_full_mimetype
+    """
 
     VERSION = 'beta'
 
diff --git a/pygithub3/services/repos.py b/pygithub3/services/repos.py
index b20d317..3643633 100644
--- a/pygithub3/services/repos.py
+++ b/pygithub3/services/repos.py
@@ -148,7 +148,7 @@ class Commits(Service, MimeTypeMixin):
         self._delete(request)
 
 
-class Collaborator(Service):
+class Collaborators(Service):
 
     def list(self, user=None, repo=None):
         request = self.make_request('repos.collaborators.list',
@@ -172,9 +172,10 @@ class Collaborator(Service):
 
 
 class Repo(Service):
+    """ Consume `Repos API <http://developer.github.com/v3/repos>`_ """
 
     def __init__(self, **config):
-        self.collaborators = Collaborator(**config)
+        self.collaborators = Collaborators(**config)
         self.commits = Commits(**config)
         self.downloads = Downloads(**config)
         self.forks = Forks(**config)
diff --git a/pygithub3/services/users.py b/pygithub3/services/users.py
index 2bf4302..8c436e6 100644
--- a/pygithub3/services/users.py
+++ b/pygithub3/services/users.py
@@ -5,71 +5,216 @@ from .base import Service
 
 
 class Keys(Service):
+    """ Consume `Keys API <http://developer.github.com/v3/users/keys/>`_
+
+    .. warning::
+
+        You must be authenticated for all requests
+    """
 
     def list(self):
+        """ Get public keys
+
+        It returns a :doc:`result`
+        """
         request = self.make_request('users.keys.list')
         return self._get_result(request)
 
     def get(self, key_id):
+        """ 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)
         return self._get(request)
 
     def add(self, data):
+        """ Add a public key
+
+        :param dict data: Key (title and key attributes required)
+
+        ::
+
+            key_service.add(dict(title='host', key='ssh-rsa AAA...'))
+        """
         request = self.make_request('users.keys.add',
             body=data)
         return self._post(request)
 
     def update(self, key_id, data):
+        """ Update a public key
+
+        :param int key_id: Key id
+        :param dict data: Key (title and key attributes required)
+
+        ::
+
+            key_service.update(42, dict(title='host', key='ssh-rsa AAA...'))
+        """
         request = self.make_request('users.keys.update',
             key_id=key_id, body=data)
         return self._patch(request)
 
     def delete(self, key_id):
+        """ 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)
         self._delete(request)
 
 
 class Followers(Service):
+    """ Consume `Followers API
+    <http://developer.github.com/v3/users/followers/>`_
+    """
 
     def list(self, user=None):
+        """ Get user's followers
+
+        :param str user: Username
+
+        It returns a :doc:`result`
+
+        If you call it without user and you are authenticated, get the
+        authenticated user's followers
+
+        .. warning::
+
+            If you aren't authenticated and call without user, it returns 403
+
+        ::
+
+            followers_service.list()
+            followers_service.list('octocat')
+        """
         request = self.make_request('users.followers.list', user=user)
         return self._get_result(request)
 
     def list_following(self, user=None):
+        """ Get who a user is following
+
+        :param str user: Username
+
+        It returns a :doc:`result`
+
+        If you call it without user and you are authenticated, get the
+        authenticated user's followings
+
+        .. warning::
+
+            If you aren't authenticated and call without user, it returns 403
+
+        ::
+
+            followers_service.list_following()
+            followers_service.list_following('octocat')
+        """
         request = self.make_request('users.followers.listfollowing', user=user)
         return self._get_result(request)
 
     def is_following(self, user):
+        """ 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)
 
     def follow(self, user):
+        """ Follow a user
+
+        :param str user: Username
+
+        .. warning::
+
+            You must be authenticated
+
+        ::
+
+            followers_service.follow('octocat')
+        """
         request = self.make_request('users.followers.follow', user=user)
         self._put(request)
 
     def unfollow(self, user):
+        """ Unfollow a user
+
+        :param str user: Username
+
+        .. warning::
+
+            You must be authenticated
+
+        ::
+
+            followers_service.unfollow('octocat')
+        """
         request = self.make_request('users.followers.unfollow', user=user)
         self._delete(request)
 
 
 class Emails(Service):
+    """ Consume `Emails API <http://developer.github.com/v3/users/emails/>`_
+
+    .. warning::
+
+        You must be authenticated for all requests
+    """
 
     def list(self):
+        """ Get user's emails
+
+        It returns a :doc:`result`
+        """
         request = self.make_request('users.emails.list')
         return self._get_result(request)
 
     def add(self, *emails):
+        """ Add emails
+
+        :param list emails: Emails to add
+
+        .. note::
+
+            It reject non-valid emails
+
+        ::
+
+            email_service.add('test1@xample.com', 'test2@xample.com')
+        """
         request = self.make_request('users.emails.add', body=emails)
         return self._post(request)
 
     def delete(self, *emails):
+        """ Delete emails
+
+        :param list emails: List of emails
+
+        ::
+
+            email_service.delete('test1@xample.com', 'test2@xample.com')
+        """
         request = self.make_request('users.emails.delete', body=emails)
         self._delete(request)
 
 
 class User(Service):
+    """ Consume `Users API <http://developer.github.com/v3/users>`_ """
 
     def __init__(self, **config):
         self.keys = Keys(**config)
@@ -78,9 +223,33 @@ class User(Service):
         super(User, self).__init__(**config)
 
     def get(self, user=None):
+        """ Get a single user
+
+        :param str user: Username
+
+        If you call it without user and you are authenticated, get the
+        authenticated user.
+
+        .. warning::
+
+            If you aren't authenticated and call without user, it returns 403
+
+        ::
+
+            user_service.get('copitux')
+            user_service.get()
+        """
         request = self.make_request('users.get', user=user)
         return self._get(request)
 
     def update(self, data):
+        """ Update the authenticated user
+
+        :param dict data: Input to update
+
+        ::
+
+            user_service.update(dict(name='new_name', bio='new_bio'))
+        """
         request = self.make_request('users.update', body=data)
         return self._patch(request)