Improve docs.

Author: Jeff-Meadows

README.rst

@@ -262,20 +262,18 @@ supported by the SDK. You can still use these endpoints by using the ``make_requ
 .. code-block:: python
 
     # https://box-content.readme.io/reference#get-metadata-schema
-    from boxsdk.config import API
     # Returns a Python dictionary containing the result of the API request
     json_response = client.make_request(
         'GET',
-        '{0}/metadata_templates/enterprise/customer/schema'.format(API.BASE_API_URL),
+        client.get_url('metadata_templates', 'enterprise', 'customer', 'schema'),
     ).json()
 
 ``make_request()`` takes two parameters:
 
 - ``method`` -an HTTP verb like ``GET`` or ``POST``
 - ``url`` - the URL of the requested API endpoint
 
-``boxsdk.config.API`` is an object specifying which URLs to use in order to access the Box API. It can be used for
-formatting the URLs to use with ``make_request``. Box objects also have a ``get_url`` method. Pass it an endpoint
+The ``Client`` class and Box objects have a ``get_url`` method. Pass it an endpoint
 to get the correct URL for use with that object and endpoint.
 
 Box Developer Edition

boxsdk/client/client.py

@@ -16,6 +16,7 @@
 from ..object.group_membership import GroupMembership
 from ..util.shared_link import get_shared_link_header
 from ..util.translator import Translator
+from ..util.url import get_url
 
 
 class Client(object):
@@ -393,3 +394,21 @@ def with_shared_link(self, shared_link, shared_link_password):
             self._network,
             self._session.with_shared_link(shared_link, shared_link_password),
         )
+
+    def get_url(self, endpoint, *args):
+        """
+        Return the URL for the given Box API endpoint.
+
+        :param endpoint:
+            The name of the endpoint.
+        :type endpoint:
+            `url`
+        :param args:
+            Additional parts of the endpoint URL.
+        :type args:
+            `Iterable`
+        :rtype:
+            `unicode`
+        """
+        # pylint:disable=no-self-use
+        return get_url(endpoint, *args)

boxsdk/object/base_endpoint.py

@@ -1,7 +1,8 @@
 # coding: utf-8
 
 from __future__ import unicode_literals
-from boxsdk.config import API
+
+from boxsdk.util.url import get_url
 
 
 class BaseEndpoint(object):
@@ -33,9 +34,7 @@ def get_url(self, endpoint, *args):
             `unicode`
         """
         # pylint:disable=no-self-use
-        url = ['{0}/{1}'.format(API.BASE_API_URL, endpoint)]
-        url.extend(['/{0}'.format(x) for x in args])
-        return ''.join(url)
+        return get_url(endpoint, *args)
 
     def as_user(self, user):
         """

boxsdk/util/url.py

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from boxsdk.config import API
+
+
+def get_url(endpoint, *args):
+    """
+    Return the URL for the given Box API endpoint.
+
+    :param endpoint:
+        The name of the endpoint.
+    :type endpoint:
+        `url`
+    :param args:
+        Additional parts of the endpoint URL.
+    :type args:
+        `Iterable`
+    :rtype:
+        `unicode`
+    """
+    url = ['{0}/{1}'.format(API.BASE_API_URL, endpoint)]
+    url.extend(['/{0}'.format(x) for x in args])
+    return ''.join(url)

docs/source/boxsdk.util.rst

@@ -84,6 +84,14 @@ boxsdk.util.translator module
     :undoc-members:
     :show-inheritance:
 
+boxsdk.util.url module
+----------------------
+
+.. automodule:: boxsdk.util.url
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 
 Module contents
 ---------------

docs/source/index.rst

@@ -3,15 +3,98 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to The Box Python SDK's documentation!
-===================================
+Box Python SDK
+==============
 
-Contents:
+
+Installing
+----------
+
+.. code-block:: console
+
+    pip install boxsdk
+
+
+Source Code
+-----------
+
+https://github.com/box/box-python-sdk
+
+
+Quickstart
+----------
+
+Create a developer token from your app's configuration page (https://app.box.com/developers/services).
+
+You'll be prompted for it on the command line.
+
+.. code-block:: pycon
+
+    $ from boxsdk import DevelopmentClient
+    $ client = DevelopmentClient()
+    >>> Enter developer token: <enter your developer token>
+    $ me = client.user().get()
+
+    GET https://api.box.com/2.0/users/me {'headers': {u'Authorization': u'Bearer ----KkeV',
+                 u'User-Agent': u'box-python-sdk-1.4.3'},
+     'params': None}
+
+    {"type":"user","id":"----6009","name":"Jeffrey Meadows","login":"[email protected]",...}
+
+    $ me.name
+    >>> Jeffrey Meadows
+
+The ``DevelopmentClient`` uses Box developer tokens for auth (and will prompt you for a new token upon
+expiration), and logs API requests and responses, making it really easy to get started learning the SDK and Box API.
+
+
+Creating an App for Users
+-------------------------
+
+Authorization
+~~~~~~~~~~~~~
+
+If you'd like other users to use your app, you need to set up a way for them to authorize your app and
+grant it access to their Box account. The ``auth`` module contains several classes to help you do that.
+
+The simplest class is the ``OAuth2`` class. To use it, instantiate it with your ``client_id`` and ``client_secret``.
+
+Follow the `tutorial on GitHub <https://github.com/box/box-python-sdk/blob/master/README.rst#id2>`_ for
+instructions on how to get an authorized client for a user. Using the ``store_tokens`` callback, you may persist
+the user's auth and refresh tokens for the next time they use your app. Once they return to your app, you can
+create an authorized client like so:
+
+.. code-block:: python
+
+    from boxsdk import OAuth2, Client
+
+    oauth = OAuth2(
+        client_id='YOUR_CLIENT_ID',
+        client_secret='YOUR_CLIENT_SECRET',
+        store_tokens=your_store_tokens_callback_method,
+        access_token=persisted_access_token,
+        refresh_token=persisted_refresh_token,
+    )
+    client = Client(oauth)
+
+
+Making requests to Box
+~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have an authorized client, you can use it to make requests to Box on your user's behalf. The client
+has several methods to help you get started, many of which return Box objects, which, in turn, have methods that
+correspond to Box API endpoints.
+
+The module documentation below describes each of these methods and which parameters they require. Some API endpoints
+do not have corresponding SDK methods; for those, you can use the generic ``make_request`` method of the client.
+
+Module Documentation
+--------------------
 
 .. toctree::
-   :maxdepth: 4
+    :maxdepth: 4
 
-   boxsdk
+    boxsdk
 
 
 Indices and tables