Update events docs

copitux · copitux · commit caa25dcfd756 · 2012-09-20T17:39:01.000+02:00
diff --git a/docs/events.rst b/docs/events.rst
@@ -3,14 +3,15 @@
 Events service
 ==============
 
-This service exposes the `Events API`. Much of this API is read-only, and while
+This service exposes the `Events API`_. Much of this API is read-only, and while
 pagination is supported, there is a fixed page size of 30 with a limit of 10
-page requests. 
+page requests.
 
-Many events have an `actor` which denotes the user that performed an event. 
-Additionally, there may be `org` or `repo` attributes for events related to 
-Organizations and Repos. Finally, each event object contains a `payload` 
+Many events have an `actor` which denotes the user that performed an event.
+Additionally, there may be `org` or `repo` attributes for events related to
+Organizations and Repos. Finally, each event object contains a `payload`
 attribute containing more detailed information about the event.
+
 .. _public events:
 
 Public Events
@@ -26,14 +27,39 @@ Yields the most recent public events from Github.
     events = gh.events.list().all()
     print events[0].payload
 
+Event
+.......
+
+.. autoclass:: pygithub3.services.events.Event
+    :members:
+
+    .. attribute:: issues
+
+        :ref:`Issues events <Issues events service>`
+
+    .. attribute:: networks
+
+        :ref:`Events network service`
+
+    .. attribute:: orgs
+
+        :ref:`Events org service`
+
+    .. attribute:: repos
+
+        :ref:`Events repo service`
+
+    .. attribute:: users
+
+        :ref:`Events user service`
 
 .. _repository events:
 
 Repo Events
 -----------
 
-These are events for a specific repo, including issue and network events. The 
-Issues events are proxied to the `Issues Service`_.
+These are events for a specific repo, including issue and network events. The
+Issues events are proxied to the :ref:`Issues service`.
 
 ::
 
@@ -42,12 +68,30 @@ Issues events are proxied to the `Issues Service`_.
         print("{t}".format(t=e.type))
 
     # Get the issue Events
-    events = gh.events.issues.list_by_repo(user="copitux", 
+    events = gh.events.issues.list_by_repo(user="copitux",
                                            repo="python-github3")
 
     # Get the Public Events for a Repo's Network
     events = gh.events.networks.list(user="copitux", repo="python-github3")
-    
+
+.. _Events network service:
+
+Network
+.......
+
+.. autoclass:: pygithub3.services.events.networks.Network
+    :members:
+
+
+.. _Events repo service:
+
+Repo
+........
+
+.. autoclass:: pygithub3.services.events.repos.Repo
+    :members:
+
+
 .. _organziation events:
 
 Organization Events
@@ -60,19 +104,27 @@ These are the public events for an Organization
     events = gh.events.orgs.list(org="Acme")
 
 You may also get a user's feed of events for an Organization, but you *must* be
-authenticated as the provided user, and you must be a member of the given 
+authenticated as the provided user, and you must be a member of the given
 organization.
 
 ::
-    
+
     events = gh.events.users.orgs(user="copitux", org="acme")
 
+.. _Events org service:
+
+Org
+........
+
+.. autoclass:: pygithub3.services.events.orgs.Org
+    :members:
+
 .. _user events:
 
 User Events
 -----------
 
-You can retrieve the public events performed by a user and the public events 
+You can retrieve the public events performed by a user and the public events
 that a user receives. If you're authenticated, you may also receive private
 events.
 
@@ -84,10 +136,15 @@ events.
 If authenticated as `copitux`, you could get private events with the
 following, otherwise you'll just get the public events as above:
 
-:: 
+::
 
     received_events = gh.events.users.list_received(user="copitux")
     performed_events = gh.events.users.list_performed(user="copitux")
 
+.. _Events user service:
+
+User
+........
 
-.. _Events API: http://developer.github.com/v3/events/
+.. autoclass:: pygithub3.services.events.users.User
+    :members:
diff --git a/docs/issues.rst b/docs/issues.rst
@@ -25,7 +25,7 @@ Issues
 
     .. attribute:: events
 
-        :ref:`Events service`
+        :ref:`Issues events service`
 
     .. attribute:: labels
 
@@ -43,7 +43,7 @@ Comments
 .. autoclass:: pygithub3.services.issues.Comments
     :members:
 
-.. _Events service:
+.. _Issues events service:
 
 Events
 ------
diff --git a/pygithub3/services/events/__init__.py b/pygithub3/services/events/__init__.py
@@ -26,15 +26,17 @@ def list(self):
         :returns: A :doc:`result`
 
         .. note::
+            Hits the API fetching maximum number of events (300 = 30/page * 10)
+        """
+
+        """ TODO
             This method uses ``_get_normal_result`` which hits the API fetching
             maximum number of events (300 = 30/page * 10).
 
             If there's a good way to tell ``smart.Method`` about the last page
             ahead of time, that may be a better way to proceed. Otherwise it
             tries to set that via ``_set_last_page_from`` which fails because
             that data is not in the returned header.
-
-
         """
         request = self.request_builder('events.list')
         return self._get_normal_result(request, per_page=None)
diff --git a/pygithub3/services/events/networks.py b/pygithub3/services/events/networks.py
@@ -16,6 +16,8 @@ def list(self, user=None, repo=None):
         :param str repo: Repository
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.networks.list',
                                     user=user, repo=repo)
diff --git a/pygithub3/services/events/repos.py b/pygithub3/services/events/repos.py
@@ -16,10 +16,12 @@ def list(self, user=None, repo=None):
         :param str repo: Repository
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
+
         .. note::
             Remember that the Events API give 10 pages with 30 entries, up to
             300 events, so you'll only get the last 300 Repo events
-
         """
         request = self.make_request('events.repos.list', user=user, repo=repo)
         return self._get_normal_result(request)
diff --git a/pygithub3/services/events/users.py b/pygithub3/services/events/users.py
@@ -16,6 +16,8 @@ def list_received(self, user=None):
         :param str user: Username
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.users.list_received', user=user)
         return self._get_normal_result(request)
@@ -26,6 +28,8 @@ def list_received_public(self, user=None):
         :param str user: Username
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.users.list_received_public',
                                     user=user)
@@ -38,6 +42,8 @@ def list_performed(self, user=None):
         :param str user: Username
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.users.list_performed', user=user)
         return self._get_normal_result(request)
@@ -48,6 +54,8 @@ def list_performed_public(self, user=None):
         :param str user: Username
         :returns: A :doc:`result`
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.users.list_performed_public',
                                     user=user)
@@ -62,6 +70,8 @@ def orgs(self, user=None, org=None):
         .. warning::
             You must be authenticated as the given user.
 
+        .. note::
+            Remember :ref:`config precedence`
         """
         request = self.make_request('events.users.list_org_events',
                                     user=user, org=org)
diff --git a/pygithub3/services/issues/events.py b/pygithub3/services/issues/events.py
@@ -4,7 +4,7 @@
 
 
 class Events(Service):
-    """ Consume `Events API
+    """ Consume `Issues Events API
     <http://developer.github.com/v3/issues/events>`_ """
 
     def list_by_issue(self, number, user=None, repo=None):
