Services.repos.Repo doc

And typos

1 files changed, 37 insertions, 8 deletions

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