Services.repos.Repo doc

And typos

6 files changed, 174 insertions, 40 deletions

diff --git a/docs/conf.py b/docs/conf.py
index d3d00a6..7b87720 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -93,7 +93,6 @@ highlight_language = 'python'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinxdoc'
 #html_theme = 'werkzeug'
 
 # Theme options are theme-specific and customize the look and feel of a theme
diff --git a/docs/repos.rst b/docs/repos.rst
index 73aadb2..f6dbead 100644
--- a/docs/repos.rst
+++ b/docs/repos.rst
@@ -7,17 +7,44 @@ Repos's services
 
     from pygithub3 import Github
 
-    auth = dict(login='octocat', password='pass')
-    gh = Github(**auth)
+    gh = Github()
 
-    # Get copitux user
-    gh.users.get('copitux')
+    django_compressor = gh.repos.get(user='jezdez', repo='django_compressor')
+    requests_collaborators = gh.repos.collaborators(user='kennethreitz',
+        repo='requests')
 
-    # Get copitux's followers
-    gh.users.followers.list('copitux')
+.. _config precedence:
 
-    # Get octocat's emails
-    gh.users.emails.list()
+Config precedence
+------------------
+
+Some request always need ``user`` and ``repo`` parameters, both, to identify
+a `repository`. Because there are a lot of requests which need that parameters,
+you can :ref:`config each service` with ``user`` and ``repo`` globally.
+
+So several requests follow a simple precedence ``user_in_arg > user_in_config``
+
+You can see it better with an example: ::
+
+    from pygithub3 import Github
+
+    gh = Github(user='octocat', repo='oct_repo')
+    oct_repo = gh.repos.get()
+    another_repo_from_octocat = gh.repos.get(repo='another_repo')
+
+    django_compressor = gh.repos.get(user='jezdez', repo='django_compressor')
+
+.. note::
+
+    Remember that each service is isolated from the rest ::
+
+        # continue example...
+        gh.repos.commits.set_user('copitux')
+        oct_repo = gh.repos.get()
+        oct_repo_collaborators = gh.repos.collaborators.list().all()
+
+        # Fail because copitux/oct_repo doesn't exist
+        gh.repos.commits.list_comments()
 
 Repo
 -------
@@ -82,3 +109,5 @@ Keys
 
 Watchers
 ---------
+
+.. _github repo doc: http://developer.github.com/v3/repos
diff --git a/docs/services.rst b/docs/services.rst
index ddd8c89..8611455 100644
--- a/docs/services.rst
+++ b/docs/services.rst
@@ -22,8 +22,10 @@ For example: ::
         commits => services.repos.commits
         ....
 
-Each service has the functions to throw the API requests and is isolated
-from the rest.
+Each service has the functions to throw the API requests and **is isolated
+from the rest**.
+
+.. _config each service:
 
 Config each service
 .....................................
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
 
         ::