Start cleaning up our API documentation

sigmavirus24 · sigmavirus24 · commit 3440d73a9684 · 2018-03-22T21:02:18.000-05:00
diff --git a/docs/source/api-reference/api.rst b/docs/source/api-reference/api.rst
@@ -1,7 +1,8 @@
 .. _api:
 
-API
-===
+==========================
+ Anonymous Functional API
+==========================
 
 .. module:: github3
 .. module:: github3.api
@@ -11,162 +12,103 @@ beautifully written module which allows the user (developer) to interact with
 ``github3.py`` elegantly and easily.
 
 Module Contents
----------------
+===============
 
 To interact with the GitHub API you can either authenticate to access protected
 functionality or you can interact with it anonymously. Authenticating provides
 more functionality to the the user (developer).
 
-To authenticate, you simply use :func:`github3.login`.
+To authenticate, you may use :func:`github3.login`.
 
 .. autofunction:: github3.login
 
-With the :class:`GitHub <github3.github.GitHub>` object that is returned you have access
-to more functionality. See that object's documentation for more information.
+With the :class:`~github3.github.GitHub` object that is returned you have
+access to more functionality. See that object's documentation for more
+information.
 
-To use the API anonymously, you can create a new
-:class:`GitHub <github3.github.GitHub>` object, e.g.,
+To use the API anonymously, you can also create a new
+:class:`~github3.github.GitHub` object, e.g.,
 
-::
+.. code-block:: python
 
     from github3 import GitHub
 
     gh = GitHub()
 
-Or you can simply use the following functions
+Or you can use the following functions:
 
-------
+Anonymous Functions
+-------------------
 
 .. autofunction:: github3.authorize
 
-------
-
 .. autofunction:: github3.create_gist
 
-------
-
 .. autofunction:: github3.gist
 
-------
-
 .. autofunction:: github3.gitignore_template
 
-------
-
 .. autofunction:: github3.gitignore_templates
 
-------
-
 .. autofunction:: github3.issue
 
-------
-
 .. autofunction:: github3.issues_on
 
-------
-
 .. autofunction:: github3.all_repositories
 
-------
-
 .. autofunction:: github3.all_users
 
-------
-
 .. autofunction:: github3.all_events
 
-------
-
 .. autofunction:: github3.followers_of
 
-------
-
 .. autofunction:: github3.followed_by
 
-------
-
 .. autofunction:: github3.public_gists
 
-------
-
 .. autofunction:: github3.gists_by
 
-------
-
 .. autofunction:: github3.organizations_with
 
-------
-
 .. autofunction:: github3.repositories_by
 
-------
-
 .. autofunction:: github3.starred_by
 
-------
-
 .. autofunction:: github3.subscriptions_for
 
-------
-
 .. autofunction:: github3.markdown
 
-------
-
 .. autofunction:: github3.octocat
 
-------
-
 .. autofunction:: github3.organization
 
-------
-
 .. autofunction:: github3.pull_request
 
-------
-
 .. autofunction:: github3.rate_limit
 
-------
-
 .. autofunction:: github3.repository
 
-------
-
 .. autofunction:: github3.search_code
 
-------
-
 .. autofunction:: github3.search_issues
 
-------
-
 .. autofunction:: github3.search_repositories
 
-------
-
 .. autofunction:: github3.search_users
 
-------
-
 .. autofunction:: github3.user
 
-------
-
 .. autofunction:: github3.zen
 
-------
-
 Enterprise Use
---------------
+==============
 
-If you're using github3.py to interact with an enterprise installation of 
-GitHub, you must use the
-:class:`GitHubEnterprise <github3.github.GitHubEnterprise>` object. Upon 
-initialization, the only parameter you must supply is the URL of your 
+If you're using github3.py to interact with an enterprise installation of
+GitHub, you **must** use the :class:`~github3.github.GitHubEnterprise` object.
+Upon initialization, the only parameter you must supply is the URL of your
 enterprise installation, e.g.
 
-::
+.. code-block:: python
 
     from github3 import GitHubEnterprise
 
diff --git a/docs/source/api-reference/auths.rst b/docs/source/api-reference/auths.rst
@@ -1,11 +1,9 @@
-.. module:: github3
-.. module:: github3.auths
-
-Authorization
-=============
+============================
+ Authorizations API Classes
+============================
 
 This part of the documentation covers the
-:class:`Authorization <Authorization>` object.
+:class:`~github3.auths.Authorization` object.
 
-.. autoclass:: Authorization
+.. autoclass:: github3.auths.Authorization
     :inherited-members:
diff --git a/docs/source/api-reference/decorators.rst b/docs/source/api-reference/decorators.rst
@@ -1,16 +1,23 @@
 .. _decorators:
 
-Decorators
-==========
+============
+ Decorators
+============
 
-.. module:: github3
-.. module:: github3.decorators
-
-This part of the documentation covers the decorators module which contains all 
+This part of the documentation covers the decorators module which contains all
 of the decorators used in github3.py.
 
+.. warning::
+
+    These decorators are only to be used internally in development of this
+    library.
+
 
-Contents
---------
+Decorator Functions
+===================
 
 .. autofunction:: github3.decorators.requires_auth
+
+.. autofunction:: github3.decorators.requires_basic_auth
+
+.. autofunction:: github3.decorators.requires_app_credentials
diff --git a/docs/source/api-reference/events.rst b/docs/source/api-reference/events.rst
@@ -1,37 +1,58 @@
-Events
-======
+====================
+ Events API Classes
+====================
 
-.. module:: github3
-.. module:: github3.events
-
-This part of the documentation covers the :class:`Event <Event>` object.
+This part of the documentation covers the objects that represent data returned
+by the Events API.
 
 Event Objects
--------------
+=============
 
-.. autoclass:: Event
+.. autoclass:: github3.events.Event
     :inherited-members:
 
 When accessing the payload of the event, you should notice that you receive a
 dictionary where the keys depend on the event type_. Note:
 
 - where they reference an array in the documentation but index it like a
   dictionary, you are given a regular dictionary
+
 - where they reference a key as returning an object, you receive the equivalent
-  object from the dictionary, e.g., for a Fork Event::
+  object from the dictionary, e.g., for a Fork Event
+
+  .. code-block:: python
 
         >>> event
         <Event [Fork]>
         >>> event.payload
         {u'forkee': <Repository [eweap/redactor-js]>}
         >>> event.payload['forkee']
-        <Repository [eweap/redactor-js]>
+        <ShortRepository [eweap/redactor-js]>
 
 Using the dictionary returned as the payload makes far more sense than creating
 an object for the payload in this instance. For one, creating a class for each
 payload type would be insanity. I did it once, but it isn't worth the effort.
 Having individual handlers as we have now which modify the payload to use our
 objects when available is more sensible.
 
+The following objects are returned as part of an
+:class:`~github3.events.Event`. These objects all have methods to convert them
+to full representations of the object. For example,
+:class:`~github3.events.EventUser` has
+:meth:`~github3.events.EventUser.to_user` and aliases
+:meth:`~github3.events.EventUser.refresh` to behave similarly.
+
+.. autoclass:: github3.events.EventUser
+
+.. autoclass:: github3.events.EventOrganization
+
+.. autoclass:: github3.events.EventPullRequest
+
+.. autoclass:: github3.events.EventReviewComment
+
+.. autoclass:: github3.events.EventIssue
+
+.. autoclass:: github3.events.EventIssueComment
+
 .. links
 .. _type: https://developer.github.com/v3/activity/events/types
