Document DJA's ability to use Compound Documents. (#308)

This branch adds documentation for how to include extra resources
under the `included` key.

It also adds Sphinx and the extra required dependencies to build
the docs to `requirements-development.txt`.

Author: mblayman

docs/usage.md

@@ -457,8 +457,53 @@ Adding `url` to `fields` on a serializer will add a `self` link to the `links` k
 
 Related links will be created automatically when using the Relationship View.
 
+### Included
+
+JSON API can include additional resources in a single network request.
+The specification refers to this feature as
+[Compound Documents](http://jsonapi.org/format/#document-compound-documents).
+Compound Documents can reduce the number of network requests
+which can lead to a better performing web application.
+To accomplish this,
+the specification permits a top level `included` key.
+The list of content within this key are the extra resources
+that are related to the primary resource.
+
+To make a Compound Document,
+you need to modify your `ModelSerializer`.
+The two required additions are `included_resources`
+and `included_serializers`.
+
+For example,
+suppose you are making an app to go on quests,
+and you would like to fetch your chosen knight
+along with the quest.
+You could accomplish that with:
+
+```python
+class KnightSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Knight
+        fields = ('id', 'name', 'strength', 'dexterity', 'charisma')
+
+
+class QuestSerializer(serializers.ModelSerializer):
+    included_serializers = {
+        'knight': KnightSerializer,
+    }
+
+    class Meta:
+        model = Quest
+        fields = ('id', 'title', 'reward', 'knight')
+
+    class JSONAPIMeta:
+        included_resources = ['knight']
+```
+
+`included_resources` informs DJA of **what** you would like to include.
+`included_serializers` tells DJA **how** you want to include it.
+
 <!--
 ### Relationships
-### Included
 ### Errors
 -->

requirements-development.txt

@@ -3,5 +3,8 @@ pytest>=2.9.0,<3.0
 pytest-django
 pytest-factoryboy
 fake-factory
+recommonmark
+Sphinx
+sphinx_rtd_theme
 tox
 mock