Add support for top-level description in API docs

rest_framework/documentation.py

@@ -6,32 +6,43 @@ from rest_framework.renderers import (
 from rest_framework.schemas import get_schema_view
 
 
-def get_docs_view(title=None, url=None, renderer_classes=None, public=True):
-    if renderer_classes is None:
-        renderer_classes = [DocumentationRenderer, CoreJSONRenderer]
+def get_docs_view(title=None, description=None, schema_url=None, public=True):
+    renderer_classes = [DocumentationRenderer, CoreJSONRenderer]
 
     return get_schema_view(
         title=title,
-        url=url,
+        url=schema_url,
+        description=description,
         renderer_classes=renderer_classes,
         public=public
     )
 
 
-def get_schemajs_view(title=None, url=None, public=True):
+def get_schemajs_view(title=None, description=None, schema_url=None, public=True):
     renderer_classes = [SchemaJSRenderer]
 
     return get_schema_view(
         title=title,
-        url=url,
+        url=schema_url,
+        description=description,
         renderer_classes=renderer_classes,
         public=public
     )
 
 
-def include_docs_urls(title=None, schema_url=None, public=True):
-    docs_view = get_docs_view(title, schema_url, public=public)
-    schema_js_view = get_schemajs_view(title, schema_url, public=public)
+def include_docs_urls(title=None, description=None, schema_url=None, public=True):
+    docs_view = get_docs_view(
+        title=title,
+        description=description,
+        schema_url=schema_url,
+        public=public
+    )
+    schema_js_view = get_schemajs_view(
+        title=title,
+        description=description,
+        schema_url=schema_url,
+        public=public
+    )
     urls = [
         url(r'^$', docs_view, name='docs-index'),
         url(r'^schema.js$', schema_js_view, name='schema-js')

rest_framework/schemas.py

@@ -275,7 +275,7 @@ class SchemaGenerator(object):
     # Set by 'SCHEMA_COERCE_PATH_PK'.
     coerce_path_pk = None
 
-    def __init__(self, title=None, url=None, patterns=None, urlconf=None):
+    def __init__(self, title=None, url=None, description=None, patterns=None, urlconf=None):
         assert coreapi, '`coreapi` must be installed for schema support.'
         assert coreschema, '`coreschema` must be installed for schema support.'
 
@@ -288,6 +288,7 @@ class SchemaGenerator(object):
         self.patterns = patterns
         self.urlconf = urlconf
         self.title = title
+        self.description = description
         self.url = url
         self.endpoints = None
 
@@ -307,7 +308,10 @@ class SchemaGenerator(object):
         if not url and request is not None:
             url = request.build_absolute_uri()
 
-        return coreapi.Document(title=self.title, url=url, content=links)
+        return coreapi.Document(
+            title=self.title, description=self.description,
+            url=url, content=links
+        )
 
     def get_links(self, request=None):
         """
@@ -661,11 +665,11 @@ class SchemaGenerator(object):
         return named_path_components + [action]
 
 
-def get_schema_view(title=None, url=None, urlconf=None, renderer_classes=None, public=False):
+def get_schema_view(title=None, url=None, description=None, urlconf=None, renderer_classes=None, public=False):
     """
     Return a schema view.
     """
-    generator = SchemaGenerator(title=title, url=url, urlconf=urlconf)
+    generator = SchemaGenerator(title=title, url=url, description=description, urlconf=urlconf)
     if renderer_classes is None:
         if renderers.BrowsableAPIRenderer in api_settings.DEFAULT_RENDERER_CLASSES:
             rclasses = [renderers.CoreJSONRenderer, renderers.BrowsableAPIRenderer]

rest_framework/templates/rest_framework/docs/document.html

@@ -3,6 +3,9 @@
 <div class="row intro">
 <div class="col-md-6 intro-title">
     <h1>{{ document.title }}</h1>
+    {% if document.description %}
+    <p>{% render_markdown document.description %}</p>
+    {% endif %}
 </div>
 <div class="col-md-6 intro-code">
     {% if 'shell' in langs %}{% include "rest_framework/docs/langs/shell-intro.html" %}{% endif %}