Resolve sphinx documentation build warnings (#711)

Author: sliverc

docs/conf.py

@@ -14,10 +14,14 @@
 # serve to show the default.
 
 import datetime
-import sys
 import os
 import shlex
+import sys
+
 import django
+from sphinx.ext.apidoc import main
+
+from rest_framework_json_api import VERSION
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -27,8 +31,7 @@
 django.setup()
 
 # Auto-generate API documentation.
-from sphinx.ext.apidoc import main
-main(['-o', 'apidoc', '-f', '-e', '-T', '-M', '../rest_framework_json_api'])
+main(['-o', '_build/apidoc', '-f', '-e', '-T', '-M', '../rest_framework_json_api'])
 
 # -- General configuration ------------------------------------------------
 
@@ -38,17 +41,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'recommonmark']
 autodoc_member_order = 'bysource'
 autodoc_inherit_docstrings = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-from recommonmark.parser import CommonMarkParser
-source_parsers = {
-    '.md': CommonMarkParser,
-}
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -71,7 +70,6 @@
 # built documents.
 #
 # The short X.Y version.
-from rest_framework_json_api import VERSION
 version = VERSION
 # The full version, including alpha/beta/rc tags.
 release = VERSION
@@ -91,7 +89,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'pull_request_template.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

rest_framework_json_api/renderers.py

@@ -26,24 +26,21 @@ class JSONRenderer(renderers.JSONRenderer):
 
     Render a JSON response per the JSON API spec:
 
-    .. code:: json
+    .. code-block:: json
 
         {
-            "data": [{
-                "type": "companies",
-                "id": 1,
-                "attributes": {
-                    "name": "Mozilla",
-                    "slug": "mozilla",
-                    "date-created": "2014-03-13 16:33:37"
-                }
-            }, {
-                "type": "companies",
-                "id": 2,
-                ...
-            }]
+          "data": [
+            {
+              "type": "companies",
+              "id": 1,
+              "attributes": {
+                "name": "Mozilla",
+                "slug": "mozilla",
+                "date-created": "2014-03-13 16:33:37"
+              }
+            }
+          ]
         }
-
     """
 
     media_type = 'application/vnd.api+json'

rest_framework_json_api/views.py

@@ -37,19 +37,20 @@ class PreloadIncludesMixin(object):
 
     __all__ can be used to specify a prefetch which should be done regardless of the include
 
+
     .. code:: python
 
-    # When MyViewSet is called with ?include=author it will prefetch author and authorbio
-    class MyViewSet(viewsets.ModelViewSet):
-        queryset = Book.objects.all()
-        prefetch_for_includes = {
-            '__all__': [],
-            'category.section': ['category']
-        }
-        select_for_includes = {
-            '__all__': [],
-            'author': ['author', 'author__authorbio'],
-        }
+        # When MyViewSet is called with ?include=author it will prefetch author and authorbio
+        class MyViewSet(viewsets.ModelViewSet):
+            queryset = Book.objects.all()
+            prefetch_for_includes = {
+                '__all__': [],
+                'category.section': ['category']
+            }
+            select_for_includes = {
+                '__all__': [],
+                'author': ['author', 'author__authorbio'],
+            }
     """
 
     def get_select_related(self, include):