Merge branch 'develop'

Makefile

@@ -5,6 +5,7 @@ DJANGO_ADMIN=$(shell which django-admin.py)
 SETTINGS_TEST=tests.testapp.settings.test
 SETTINGS_DEV=tests.testapp.settings.dev
 PARAMS_DEV=--settings=$(SETTINGS_DEV) --pythonpath=$(CURDIR)
+SPHINXBUILD=sphinx-build
 
 all: $(ENV)
 	@echo "Virtualenv is installed"
@@ -66,9 +67,9 @@ install:
 .PHONY: graph_models
 # target: graph_models - graph models
 graph_models: $(ENV)
-	$(DJANGO_ADMIN) graph_models --output=models.png $(PARAMS_DEV) testapp
+	$(DJANGO_ADMIN) graph_models --output=docs/models.png $(PARAMS_DEV) testapp
 
 .PHONY: docs
 # target: docs - build documentation
 docs:
-	echo "Build docs"
+	$(SPHINXBUILD) -b html docs docs/_build

docs/index.rst

@@ -10,10 +10,11 @@ Welcome to json:api's documentation!
    :maxdepth: 3
 
    modules.rst
+   pages/resource.rst
 
 Installation
 ============
-Requires: Django (1.5, 1.6); python (2.7, 3.3).
+Requires: Django (1.5, 1.6, 1.7); python (2.7, 3.3).
 
 .. code-block:: python
 
@@ -56,7 +57,7 @@ Features
 What makes a decent API Framework? These features:
 
     + \+ Pagination
-    + Posting of data with validation
+    + \+ Posting of data with validation
     + \+ Publishing of metadata along with querysets
     + \+ API discovery
     + Proper HTTP response handling
@@ -86,10 +87,14 @@ Examples
 ========
 curl -v -H "Content-Type: application/vnd.api+json" 127.0.0.1:8000/api/author
 
+Test Application Models
+=======================
+.. image:: models.png
+
+
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/pages/resource.rst

@@ -0,0 +1,55 @@
+JSONAPI Resource
+================
+
+Resources are related to Django models.
+Basic customization is done in Resource.Meta class.
+Exampele of resource declaration is shown below:
+
+.. code-block:: python
+
+    from jsonapi.api import API
+    from jsonapi.resource import Resource
+    from django.conf import settings
+
+    api = API()
+
+    @api.register
+    class UserResource(Resource):
+        class Meta:
+            model = settings.AUTH_USER_MODEL
+            authenticators = [Resource.AUTHENTICATORS.SESSION]
+            fieldnames_exclude = 'password',
+
+
+    @api.register
+    class AuthorResource(Resource):
+        class Meta:
+            model = 'testapp.Author'
+            allowed_methods = 'GET', 'POST', 'PUT', 'DELETE'
+
+
+    @api.register
+    class PostWithPictureResource(Resource):
+        class Meta:
+            model = 'testapp.PostWithPicture'
+            fieldnames_include = 'title_uppercased',
+            page_size = 3
+
+    @staticmethod
+    def dump_document_title(obj):
+        return obj.title
+
+
+Available Meta parameters:
+
+=================== ================= ===================== =================================
+Name                Type              Default               Usage
+=================== ================= ===================== =================================
+model               str               None. Need to specify '<appname>.<modelname>'
+allowed_methods     tuple             ('GET')               tuple of capitalized HTTP methods
+authenticators      list              []                    [Resource.AUTHENTICATORS.SESSION]
+fieldnames_include  list              []                    list of field names
+fieldnames_exclude  list              []                    list of field names
+page_size           int               None                  integer if need pagination
+form                django.forms.Form Default ModelForm     form to use
+=================== ================= ===================== =================================