Skip to content

Commit 5b89a14

Browse files
sigmavirus24sigmavirus24
committed
Should round out the documentation fixes.
1 parent 4aa97e0 commit 5b89a14

18 files changed

Lines changed: 304 additions & 78 deletions

‎docs/events.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Events
2+
======
3+
4+
.. module:: github3
5+
.. module:: github3.events
6+
7+
This part of the documentation covers the :class:`Event <Event>` object.
8+
9+
Event Objects
10+
-------------
11+
12+
.. autoclass:: Event
13+
:inherited-members:
14+
15+
When accessing the payload of the event, you should notice that you receive a
16+
dictionary where the keys depend on the event type_. Note:
17+
18+
- where they reference an array in the documentation but index it like a
19+
dictionary, you are given a regular dictionary
20+
- where they reference a key as returning an object, you receive the equivalent
21+
object from the dictionary, e.g., for a Fork Event::
22+
23+
>>> event
24+
<Event [Fork]>
25+
>>> event.payload
26+
{u'forkee': <Repository [eweap/redactor-js]>}
27+
>>> event.payload['forkee']
28+
<Repository [eweap/redactor-js]>
29+
30+
Using the dictionary returned as the payload makes far more sense than creating
31+
an object for the payload in this instance. For one, creating a class for each
32+
payload type would be insanity. I did it once, but it isn't worth the effort.
33+
Having individual handlers as we have now which modify the payload to use our
34+
objects when available is more sensible.
35+
36+
.. links
37+
.. _type: http://developer.github.com/v3/events/types

‎docs/gists.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. _gists:
2+
3+
Gists
4+
=====
5+
6+
.. module:: github3
7+
.. module:: github3.gists
8+
9+
.. |Gist| replace:: :class:`Gist <Gist>`
10+
.. |GistComment| replace:: :class:`GistComment <GistComment>`
11+
.. |GistFile| replace:: :class:`GistFile <GistFile>`
12+
13+
This part of the documentation details the properties and methods associated
14+
with |Gist|, |GistComment|, and |GistFile| objects. These classes should never
15+
be instantiated by the user (developer) directly.
16+
17+
Gist Objects
18+
------------
19+
20+
.. autoclass:: Gist
21+
:inherited-members:
22+
23+
------
24+
25+
.. autoclass:: GistComment
26+
:inherited-members:
27+
28+
------
29+
30+
.. autoclass:: GistFile
31+
:inherited-members:

‎docs/index.rst‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -59,18 +59,9 @@ Modules
5959

6060
.. toctree::
6161
:maxdepth: 1
62+
:blob:
6263

63-
api
64-
event
65-
gist
66-
git
67-
github
68-
issue
69-
legacy
70-
org
71-
pulls
72-
repo
73-
user
64+
*
7465

7566
Internals
7667
~~~~~~~~~

‎docs/issues.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
.. _issue:
2+
3+
Issue
4+
=====
5+
6+
.. module:: github3
7+
.. module:: github3.issues
8+
9+
This part of the documentation covers the module which handles :class:`Issue
10+
<Issue>`\ s and their related objects:
11+
12+
- :class:`IssueComment <IssueComment>`
13+
- :class:`IssueEvent <IssueEvent>`
14+
- :class:`Milestone <Milestone>`
15+
- :class:`Label <Label>`.
16+
17+
Issue Objects
18+
-------------
19+
20+
.. autoclass:: Issue
21+
:inherited-members:
22+
23+
------
24+
25+
.. autoclass:: IssueComment
26+
:inherited-members:
27+
28+
------
29+
30+
.. autoclass:: IssueEvent
31+
:inherited-members:
32+
33+
------
34+
35+
.. autoclass:: Milestone
36+
:inherited-members:
37+
38+
------
39+
40+
.. autoclass:: Label
41+
:inherited-members:

‎docs/orgs.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. module:: github3
2+
.. module:: github3.orgs
3+
4+
Organization
5+
============
6+
7+
This section of the documentation covers:
8+
9+
- :class:`Organization <Organization>`\ s
10+
- :class:`Team <Team>`\ s
11+
12+
Organization Objects
13+
--------------------
14+
15+
.. autoclass:: Organization
16+
:inherited-members:
17+
18+
------
19+
20+
.. autoclass:: Team
21+
:inherited-members:

‎docs/repos.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
.. module:: github3
2+
.. module:: github3.repos
3+
4+
Repository
5+
==========
6+
7+
This part of the documentation covers:
8+
9+
- :class:`Repository <Repository>`
10+
- :class:`Branch <Branch>`
11+
- :class:`Contents <Contents>`
12+
- :class:`Download <Download>`
13+
- :class:`Hook <Hook>`
14+
- :class:`RepoTag <RepoTag>`
15+
- :class:`RepoComment <RepoComment>`
16+
- :class:`RepoCommit <RepoCommit>`
17+
- :class:`Comparison <Comparison>`
18+
19+
None of these objects should be instantiated directly by the user (developer).
20+
These are here for reference only.
21+
22+
More information for about this class can be found in the official
23+
`documentation <http://developer.github.com/v3/repos>`_ and in various other
24+
sections of the GitHub documentation.
25+
26+
Repository Objects
27+
------------------
28+
29+
.. autoclass:: Repository
30+
:inherited-members:
31+
32+
---------
33+
34+
.. autoclass:: Branch
35+
:inherited-members:
36+
37+
---------
38+
39+
.. autoclass:: Contents
40+
:inherited-members:
41+
42+
---------
43+
44+
.. autoclass:: Download
45+
:inherited-members:
46+
47+
---------
48+
49+
.. autoclass:: Hook
50+
:inherited-members:
51+
52+
---------
53+
54+
.. autoclass:: RepoTag
55+
:inherited-members:
56+
57+
---------
58+
59+
More information about this class can be found in the official documentation
60+
about `comments <http://developer.github.com/v3/repos/comments/>`_.
61+
62+
.. autoclass:: RepoComment
63+
:inherited-members:
64+
65+
---------
66+
67+
.. autoclass:: RepoCommit
68+
:inherited-members:
69+
70+
---------
71+
72+
.. autoclass:: Comparison
73+
:inherited-members:

‎docs/users.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. module:: github3
2+
.. module:: github3.users
3+
4+
User
5+
====
6+
7+
This part of the documentation covers:
8+
9+
- :class:`User <User>`
10+
- :class:`Key <Key>`
11+
- :class:`Plan <Plan>`
12+
13+
None of these objects should ever be instantiated by the user (developer).
14+
15+
User Modules
16+
------------
17+
18+
.. autoclass:: User
19+
:inherited-members:
20+
21+
------
22+
23+
.. autoclass:: Key
24+
:inherited-members:
25+
26+
------
27+
28+
.. autoclass:: Plan
29+
:inherited-members:

‎github3/api.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ def gist(id_num):
3737
"""Get the gist identified by ``id_num``.
3838
3939
:param int id_num: (required), unique id of the gist
40-
:returns: :class:`Gist <github3.gist.Gist>`
40+
:returns: :class:`Gist <github3.gists.Gist>`
4141
"""
4242
return gh.gist(id_num)
4343

@@ -47,7 +47,7 @@ def list_gists(username=None):
4747
4848
:param str username: (optional), if provided, get the gists for this user
4949
instead of the authenticated user.
50-
:returns: list of :class:`Gist <github3.gist.Gist>`\ s
50+
:returns: list of :class:`Gist <github3.gists.Gist>`\ s
5151
"""
5252
return gh.list_gists(username)
5353

@@ -99,7 +99,7 @@ def create_gist(description, files):
9999
:param dict files: (required), file names with associated
100100
dictionaries for content, e.g.
101101
{'spam.txt': {'content': 'File contents ...'}}
102-
:returns: :class:`Gist <github3.gist.Gist>`
102+
:returns: :class:`Gist <github3.gists.Gist>`
103103
"""
104104
return gh.create_gist(description, files) # (No coverage)
105105

@@ -110,15 +110,15 @@ def issue(owner, repository, number):
110110
:param str owner: (required), repository owner
111111
:param str repository: (required), repository name
112112
:param int number: (required), issue number
113-
:returns: :class:`Issue <github3.issue.Issue>`
113+
:returns: :class:`Issue <github3.issues.Issue>`
114114
"""
115115
return gh.issue(owner, repository, number)
116116

117117

118118
def list_events():
119119
"""List all recent public events from GitHub.
120120
121-
:returns: list of :class:`Event <github3.event.Event>`\ s
121+
:returns: list of :class:`Event <github3.events.Event>`\ s
122122
"""
123123
return gh.list_events()
124124

‎github3/events.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ def __repr__(self):
3737

3838
@property
3939
def actor(self):
40-
""":class:`User <github3.user.User>` object representing the actor."""
40+
""":class:`User <github3.users.User>` object representing the
41+
actor."""
4142
return self._actor
4243

4344
@property
@@ -57,7 +58,7 @@ def list_types():
5758

5859
@property
5960
def org(self):
60-
""":class:`Organization <github3.org.Organization>` object if actor
61+
""":class:`Organization <github3.orgs.Organization>` object if actor
6162
was an org."""
6263
return self._org
6364

‎github3/gists.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,6 @@ def updated_at(self):
279279

280280
@property
281281
def user(self):
282-
""":class:`User <github3.user.User>` object representing the owner of
282+
""":class:`User <github3.users.User>` object representing the owner of
283283
the gist."""
284284
return self._user

0 commit comments

Comments
 (0)