Docs update (#159)

Update HISTORY and README for new release.

Author: kelseymorris95

HISTORY.rst

@@ -6,6 +6,40 @@ Release History
 Upcoming
 ++++++++
 
+New Release?
+++++++++++++++++++
+
+**Breaking Changes**
+
+- ``Events.get_events(...)`` now returns a list of ``Event`` instances rather than a list of ``dict``
+  representing events.  ``Event`` inherits from ``Mapping`` but will not have all the same capabilities as
+  ``dict``.
+
+  + Your code is affected if you use ``Events.get_events(...)`` and expect a list of ``dict`` rather than a list of
+    ``Mapping``.  For example, if you use ``__setitem__`` (``event['key'] = value``), ``update()``, ``copy()``, or
+    if your code depends on the ``str`` or ``repr`` of the ``Event``.  Use of ``__getitem__`` (``event['key']``),
+    ``get()``, and other ``Mapping`` methods is unaffected.  See
+    https://docs.python.org/2.7/library/collections.html#collections-abstract-base-classes for methods supported on
+    ``Mapping`` instances.
+
+  + Migration: If you still need to treat an ``Event`` as a ``dict``, you can get a deepcopy of the original ``dict``
+    using the new property on ``BaseAPIJSONObject``, ``response_object``.
+
+**Features**
+
+- Added ability to create custom subclasses of SDK objects with ``_item_type`` defined.
+- Added an ``Event`` class.
+
+**Other**
+
+- Added extra information to ``BoxAPIException``.
+- Added ``collaboration()`` method to ``Client``.
+- Reworked the class hierarchy.  Previously, ``BaseEndpoint`` was the parent of ``BaseObject`` which was the parent
+  of all smart objects.  Now ``BaseObject`` is a child of both ``BaseEndpoint`` and ``BaseAPIJSONObject``.
+  ``BaseObject`` is the parent of all objects that are a part of the REST API.  Another subclass of
+  ``BaseAPIJSONObject``, ``APIJSONObject``, was created to represent pseudo-smart objects such as ``Event`` that are not
+  directly accessible through an API endpoint.
+
 1.5.3
 ++++++++++++++++++
 

README.rst

@@ -390,6 +390,32 @@ Development Client
 For exploring the Box API, or to quickly get going using the SDK, the ``DevelopmentClient`` class combines the
 ``LoggingClient`` with the ``DeveloperTokenClient``.
 
+Customization
+-------------
+
+Custom Subclasses
+~~~~~~~~~~~~~~~~~
+
+Custom subclasses of any SDK object with an ``_item_type`` field can be defined:
+
+.. code-block:: pycon
+
+    from boxsdk import Client
+    from boxsdk import Folder
+
+    class MyFolderSubclass(Folder):
+        pass
+
+    client = Client(oauth)
+    folder = client.folder('0')
+
+    >>> print folder
+    >>> <Box MyFolderSubclass - 0>
+
+If a subclass of an SDK object with an ``_item_type`` field is defined, instances of this subclass will be
+returned from all SDK methods that previously returned an instance of the parent.  See ``BaseAPIJSONObjectMeta``
+and ``Translator`` to see how the SDK performs dynamic lookups to determine return types.
+
 Contributing
 ------------