Improve documentation for API

Automatically use docstring for documentation
Improve capitalization and article usage
Add documentation for upload_host parameter
Add reference URL
Remove periods

diff --git a/docs/api.rst b/docs/api.rst
index a1b896dd4e1da9b92229d64cb2b4fdddcc207f1e..7cade1f1a1b69c0d434ff4c12722cea3442fcf28 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,5 +1,7 @@
 .. _api_reference:
 
+.. currentmodule:: tweepy
+
 .. include:: parameters.rst
 
 *************
@@ -12,28 +14,7 @@ This page contains some basic documentation for the Tweepy module.
 :mod:`tweepy.api` --- Twitter API wrapper
 =========================================
 
-.. class:: API([auth_handler=None], [host='api.twitter.com'], [cache=None], \
-               [retry_count=0], [retry_delay=0], [retry_errors=None], \
-               [timeout=60], [parser=ModelParser], \
-               [wait_on_rate_limit=False], [proxy=None])
-
-   This class provides a wrapper for the API as provided by Twitter.
-   The functions provided in this class are listed below.
-
-   :param auth_handler: authentication handler to be used
-   :param host: general API host
-   :param cache: cache backend to use
-   :param retry_count: default number of retries to attempt when error occurs
-   :param retry_delay: number of seconds to wait between retries
-   :param retry_errors: which HTTP status codes to retry
-   :param timeout: The maximum amount of time to wait for a response from
-                   Twitter
-   :param parser: The object to use for parsing the response from Twitter
-   :param wait_on_rate_limit: Whether or not to automatically wait for rate
-                              limits to replenish
-   :param proxy: The full url to an HTTPS proxy to use for connecting to
-                 Twitter.
-
+.. autoclass:: API
 
 Timeline methods
 ----------------

diff --git a/tweepy/api.py b/tweepy/api.py
index f065181b03e7a33fa409a6c67d82e04045e7a6ba..b2d5f1c8f055955fd649dba5fbc2d3ebe296a386 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -49,34 +49,33 @@ def payload(payload_type, **payload_kwargs):
 
 
 class API:
-    """Twitter API"""
+    """This class provides a wrapper for the API as provided by Twitter.
+    The functions provided in this class are listed below.
+
+    :param auth_handler: The authentication handler to be used
+    :param host: The general REST API host server URL
+    :param upload_host: The URL of the upload server
+    :param cache: The cache to query if a GET method is used
+    :param retry_count: Number of retries to attempt when an error occurs
+    :param retry_delay: Number of seconds to wait between retries
+    :param retry_errors: Which HTTP status codes to retry
+    :param timeout: The maximum amount of time to wait for a response from
+                    Twitter
+    :param parser: The object to use for parsing the response from Twitter
+    :param wait_on_rate_limit: Whether or not to automatically wait for rate
+                               limits to replenish
+    :param proxy: The full url to an HTTPS proxy to use for connecting to
+                  Twitter
+    
+    :raise TypeError: If the given parser is not a ModelParser instance
+
+    :reference: https://developer.twitter.com/en/docs/api-reference-index
+    """
 
     def __init__(self, auth_handler=None,
                  host='api.twitter.com', upload_host='upload.twitter.com',
                  cache=None, retry_count=0, retry_delay=0, retry_errors=None,
                  timeout=60, parser=None, wait_on_rate_limit=False, proxy=''):
-        """
-        API instance constructor
-
-        :param auth_handler:
-        :param host: url of the server of the rest api,
-                     default: 'api.twitter.com'
-        :param upload_host: url of the upload server,
-                            default: 'upload.twitter.com'
-        :param cache: Cache to query if a GET method is used, default: None
-        :param retry_count: number of allowed retries, default: 0
-        :param retry_delay: delay in second between retries, default: 0
-        :param retry_errors: default: None
-        :param timeout: delay before to consider the request as timed out in
-                        seconds, default: 60
-        :param parser: ModelParser instance to parse the responses,
-                       default: None
-        :param wait_on_rate_limit: If the api wait when it hits the rate limit,
-                                   default: False
-        :param proxy: Url to use as proxy during the HTTP request, default: ''
-
-        :raise TypeError: If the given parser is not a ModelParser instance.
-        """
         self.auth = auth_handler
         self.host = host
         self.upload_host = upload_host