Init documentation

+core
+services.user
~services.repos

7 files changed, 251 insertions, 13 deletions

diff --git a/pygithub3/core/client.py b/pygithub3/core/client.py
index a9e9ad4..ce6cf7c 100644
--- a/pygithub3/core/client.py
+++ b/pygithub3/core/client.py
@@ -15,12 +15,6 @@ class Client(object):
     """ Client to send configurated requests"""
 
     def __init__(self, **kwargs):
-        """
-        It can be configurated
-
-        :login, :password, :user, :repo, :token, :per_page, :base_url, :verbose
-        """
-
         self.requester = requests.session()
         self.config = {
             'per_page': 100,
diff --git a/pygithub3/core/result.py b/pygithub3/core/result.py
index 226d6ab..9e69e7d 100644
--- a/pygithub3/core/result.py
+++ b/pygithub3/core/result.py
@@ -135,10 +135,11 @@ class Page(object):
 
 
 class Result(object):
-    """ """
+    """
+    Result is a very lazy paginator. It only do a real request when is needed
+    """
 
     def __init__(self, client, request, **kwargs):
-        """ """
         self.getter = Method(client.get, request, **kwargs)
         self.page = Page(self.getter)
 
@@ -158,9 +159,14 @@ class Result(object):
 
     @property
     def pages(self):
+        """ Total number of pages in request """
         return self.getter.last
 
     def get_page(self, page):
+        """ Get ``Page`` of resources
+
+        :param int page: Page number
+        """
         if page in xrange(1, self.pages + 1):
             return Page(self.getter, page)
         return None
diff --git a/pygithub3/github.py b/pygithub3/github.py
index 4941ffd..d05f069 100644
--- a/pygithub3/github.py
+++ b/pygithub3/github.py
@@ -6,7 +6,14 @@ from pygithub3.services.repos import Repo
 
 
 class Github(object):
-    """ Main entrance """
+    """
+    You can preconfigure all services globally with a ``config`` dict. See
+    :attr:`~pygithub3.services.base.Service`
+
+    Example::
+
+        gh = Github(user='kennethreitz', token='ABC...', repo='requests')
+    """
 
     def __init__(self, **config):
         self._users = User(**config)
@@ -14,8 +21,14 @@ class Github(object):
 
     @property
     def users(self):
+        """
+        :ref:`User service <User service>`
+        """
         return self._users
 
     @property
     def repos(self):
+        """
+        :ref:`Repos service <Repos service>`
+        """
         return self._repos
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)
diff --git a/pygithub3/tests/services/test_repos.py b/pygithub3/tests/services/test_repos.py
index 6f4ed71..e11bef7 100644
--- a/pygithub3/tests/services/test_repos.py
+++ b/pygithub3/tests/services/test_repos.py
@@ -6,7 +6,7 @@ from unittest import TestCase
 import requests
 from mock import patch, Mock
 
-from pygithub3.services.repos import (Repo, Collaborator, Commits, Downloads,
+from pygithub3.services.repos import (Repo, Collaborators, Commits, Downloads,
                                       Forks, Keys, Watchers)
 from pygithub3.resources.base import json
 from pygithub3.tests.utils.base import (mock_response, mock_response_result,
@@ -146,7 +146,7 @@ class TestRepoService(TestCase):
 class TestCollaboratorsService(TestCase):
 
     def setUp(self):
-        self.cs = Collaborator()
+        self.cs = Collaborators()
         self.cs.set_user('octocat')
         self.cs.set_repo('oc_repo')