From 040e87c6744bad2b32cf12bc8aa39845cd7c0012 Mon Sep 17 00:00:00 2001
From: Matt Layman <matthewlayman@gmail.com>
Date: Wed, 7 Dec 2016 22:12:57 -0500
Subject: [PATCH] Document DJA's ability to use Compound Documents.

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`.
---
 docs/usage.md                | 47 +++++++++++++++++++++++++++++++++++-
 requirements-development.txt |  3 +++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/docs/usage.md b/docs/usage.md
index e7d91c62..ebfff3b5 100644
--- a/docs/usage.md
+++ b/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
 -->
diff --git a/requirements-development.txt b/requirements-development.txt
index 1ac48b58..347619e2 100644
--- a/requirements-development.txt
+++ b/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