Allowed customising API documentation code samples (#5752)

* Allowed additional languages in API documentation

* Documented renderer_classes parameter and customising languages.

docs/topics/documenting-your-api.md

@@ -107,6 +107,7 @@ The `rest_framework.documentation` module provides three helper functions to hel
 * `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
 * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
+* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`.
 
 #### `get_docs_view`
 
@@ -117,7 +118,8 @@ The `rest_framework.documentation` module provides three helper functions to hel
 * `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
 * `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
-* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
+* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`.
+* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats.
 
 #### `get_schemajs_view`
 
@@ -130,6 +132,25 @@ The `rest_framework.documentation` module provides three helper functions to hel
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
 * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
 
+
+### Customising code samples
+
+The built-in API documentation includes automatically generated code samples for
+each of the available API client libraries.
+
+You may customise these samples by subclassing `DocumentationRenderer`, setting
+`languages` to the list of languages you wish to support:
+
+    from rest_framework.renderers import DocumentationRenderer
+
+
+    class CustomRenderer(DocumentationRenderer):
+        languages = ['ruby', 'go']
+
+For each language you need to provide an `intro` template, detailing installation instructions and such,
+plus a generic template for making API requests, that can be filled with individual request details.
+See the [templates for the bundled languages][client-library-templates] for examples.
+
 ---
 
 ## Third party packages
@@ -314,3 +335,4 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
 [image-self-describing-api]: ../img/self-describing.png
 [schemas-examples]: ../api-guide/schemas/#example
 [metadata-docs]: ../api-guide/metadata/
+[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs

rest_framework/documentation.py

@@ -11,7 +11,10 @@ def get_docs_view(
         title=None, description=None, schema_url=None, public=True,
         patterns=None, generator_class=SchemaGenerator,
         authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
-        permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
+        permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
+        renderer_classes=None):
+
+    if renderer_classes is None:
         renderer_classes = [DocumentationRenderer, CoreJSONRenderer]
 
     return get_schema_view(
@@ -51,7 +54,8 @@ def include_docs_urls(
         title=None, description=None, schema_url=None, public=True,
         patterns=None, generator_class=SchemaGenerator,
         authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
-        permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
+        permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
+        renderer_classes=None):
     docs_view = get_docs_view(
         title=title,
         description=description,
@@ -60,6 +64,7 @@ def include_docs_urls(
         patterns=patterns,
         generator_class=generator_class,
         authentication_classes=authentication_classes,
+        renderer_classes=renderer_classes,
         permission_classes=permission_classes,
     )
     schema_js_view = get_schemajs_view(

rest_framework/renderers.py

@@ -830,6 +830,8 @@ class DocumentationRenderer(BaseRenderer):
         return {
             'document': data,
             'langs': self.languages,
+            'lang_htmls': ["rest_framework/docs/langs/%s.html" % l for l in self.languages],
+            'lang_intro_htmls': ["rest_framework/docs/langs/%s-intro.html" % l for l in self.languages],
             'code_style': pygments_css(self.code_style),
             'request': request
         }

rest_framework/templates/rest_framework/docs/document.html

@@ -8,9 +8,9 @@
     {% endif %}
 </div>
 <div class="col-md-6 intro-code">
-    {% if 'shell' in langs %}{% include "rest_framework/docs/langs/shell-intro.html" %}{% endif %}
+    {% for html in lang_intro_htmls %}
-    {% if 'python' in langs %}{% include "rest_framework/docs/langs/python-intro.html" %}{% endif %}
+        {% include html %}
-    {% if 'javascript' in langs %}{% include "rest_framework/docs/langs/javascript-intro.html" %}{% endif %}
+    {% endfor %}
 </div>
 </div>
 {% if document|data %}

rest_framework/templates/rest_framework/docs/index.html

@@ -51,6 +51,7 @@
                 $('#auth-control').children().removeClass('active');
                 $('#auth-control').find("[data-auth='session']").closest('li').addClass('active');
             {% endif %}
+	    $('pre.highlight').filter('[data-language="{{ langs | first }}"]').removeClass('hide');
         </script>
     </body>
 </html>

rest_framework/templates/rest_framework/docs/langs/shell-intro.html

@@ -1,3 +1,3 @@
 {% load rest_framework %}
-<pre class="highlight shell" data-language="shell"><code>{% code bash %}# Install the command line client
+<pre class="highlight shell hide" data-language="shell"><code>{% code bash %}# Install the command line client
 $ pip install coreapi-cli{% endcode %}</code></pre>

rest_framework/templates/rest_framework/docs/langs/shell.html

@@ -1,5 +1,5 @@
 {% load rest_framework %}
-<pre class="highlight shell" data-language="shell"><code>{% code bash %}# Load the schema document
+<pre class="highlight shell hide" data-language="shell"><code>{% code bash %}# Load the schema document
 $ coreapi get {{ document.url }}{% if schema_format %} --format {{ schema_format }}{% endif %}
 
 # Interact with the API endpoint

rest_framework/templates/rest_framework/docs/link.html

@@ -93,9 +93,9 @@
 </div>
 
     <div class="col-md-6 code-samples">
-        {% if 'shell' in langs %}{% include "rest_framework/docs/langs/shell.html" %}{% endif %}
+        {% for html in lang_htmls %}
-        {% if 'python' in langs %}{% include "rest_framework/docs/langs/python.html" %}{% endif %}
+            {% include html %}
-        {% if 'javascript' in langs %}{% include "rest_framework/docs/langs/javascript.html" %}{% endif %}
+        {% endfor %}
     </div>
 </div>
 

rest_framework/templates/rest_framework/docs/sidebar.html

@@ -31,12 +31,12 @@
             </ul>
 
             <li data-toggle="collapse" data-target="#language-control" class="collapsed">
-                <a><i class="fa fa-code fa-lg"></i> Source Code</a> <span id="selected-language">shell</span>
+                <a><i class="fa fa-code fa-lg"></i> Source Code</a> <span id="selected-language">{{ langs | first }}</span>
             </li>
             <ul class="sub-menu collapse out" id="language-control">
-                <li class="active"><a href="#" data-language="shell">shell</a></li>
+            {% for lang in langs %}
-                <li><a href="#" data-language="javascript">javascript</a></li>
+                <li{% if loop.first %} class="active"{% endif %}><a href="#" data-language="{{ lang }}">{{ lang }}</a></li>
-                <li><a href="#" data-language="python">python</a></li>
+	    {% endfor %}
             </ul>
         </ul>