Merge 28f7c547b6 into 3dab905656

rest_framework/static/rest_framework/docs/css/base.css

@@ -115,6 +115,13 @@ pre.highlight code {
   background-color: #020203;
 }
 
+.sidebar .menu-list li.collapsed + ul.menu-content {
+  height: 0;
+}
+
+.sidebar .menu-list li.collapsed + ul.menu-content li {
+  display: none;
+}
 
 .sidebar .menu-list ul .sub-menu li a,
 .sidebar .menu-list li .sub-menu li a {

rest_framework/templates/rest_framework/docs/_recursive_document.html

@@ -0,0 +1,16 @@
+{% load rest_framework %}
+{% for section_key, section in items %}
+    {% if section_key %}
+        <h{{level}} id="{{ path|list_add:section_key|join:'-'|slugify }}" class="coredocs-section-title">
+            {{ section_key }}
+            <a href="#{{ path|list_add:section_key|join:'-'|slugify }}"><i class="fa fa-link" aria-hidden="true"></i></a>
+        </h{{level}}>
+    {% endif %}
+
+    {% if section.links|items %}
+        {% for link_key, link in section.links|items %}
+            {% include "rest_framework/docs/link.html" with path=path %}
+        {% endfor %}
+    {% endif %}
+    {% include 'rest_framework/docs/_recursive_document.html' with items=section.data|items path=path|list_add:section_key level=level|add:1 %}
+{% endfor %}

rest_framework/templates/rest_framework/docs/_recursive_menu.html

@@ -0,0 +1,18 @@
+{% load rest_framework %}
+{% if items %}
+<ul id="{% if path %}{{ path|join:"-"|slugify }}-dropdown{% else %}menu-content{% endif %}" class="menu-content collapse out">
+    {% for section_key, section in items %}
+        <li data-toggle="collapse" data-target="#{{ path|list_add:section_key|join:"-"|slugify }}-dropdown" class="collapsed">
+          <a><i class="fa fa-dot-circle-o fa-lg"></i> {% for p in path %}{{ p }}/{% endfor %}{% if section_key %}{{ section_key }}{% else %}API Endpoints{% endif %} <span class="arrow"></span></a>
+        </li>
+        {% if section.links|items %}
+            <ul class="sub-menu {% if section_key %}collapse{% endif %}" id="{{ path|list_add:section_key|join:'-'|slugify }}-dropdown">
+                {% for link_key, link in section.links|items %}
+                <li><a href="#{{ path|list_add:section_key|list_add:link_key|join:"-"|slugify }}">{{ link.title|default:link_key }}</a></li>
+                {% endfor %}
+            </ul>
+        {% endif %}
+        {% include "rest_framework/docs/_recursive_menu.html" with items=section.data|items path=path|list_add:section_key %}
+    {% endfor %}
+</ul>
+{% endif %}

rest_framework/templates/rest_framework/docs/document.html

@@ -14,17 +14,8 @@
 </div>
 </div>
 
-{% for section_key, section in document.data|items %}
-{% if section_key %}
-    <h2 id="{{ section_key }}" class="coredocs-section-title">{{ section_key }} <a href="#{{ section_key }}"><i class="fa fa-link" aria-hidden="true"></i>
-</a></h2>
-{% endif %}
-
-    {% for link_key, link in section.links|items %}
-        {% include "rest_framework/docs/link.html" %}
-    {% endfor %}
-{% endfor %}
+{% include "rest_framework/docs/_recursive_document.html" with items=document.data|items path=""|make_list level=2 %}
 
 {% for link_key, link in document.links|items %}
-    {% include "rest_framework/docs/link.html" %}
+    {% include "rest_framework/docs/link.html" with path=""|make_list %}
 {% endfor %}

rest_framework/templates/rest_framework/docs/interact.html

@@ -16,7 +16,7 @@
 
     </div>
 
-    <form data-key='["{{ section_key }}", "{{ link_key }}"]' class="api-interaction">
+    <form data-key='[{% for p in path %}"{{ p }}", {% endfor %}"{{ section_key }}", "{{ link_key }}"]' class="api-interaction">
     <div class="modal-body">
       <div class="row">
         <div class="col-lg-6 request">

rest_framework/templates/rest_framework/docs/langs/javascript.html

@@ -6,7 +6,7 @@ var schema = window.schema    // Loaded by `schema.js`
 var client = new coreapi.Client()
 
 // Interact with the API endpoint
-var action = [{% if section_key %}"{{ section_key }}", {% endif %}"{{ link_key }}"]
+var action = [{% for p in path %}"{{ p }}", {% endfor %}{% if section_key %}"{{ section_key }}", {% endif %}"{{ link_key }}"]
 {% if link.fields %}var params = {
 {% for field in link.fields %}    {{ field.name }}: ...{% if not loop.last %},{% endif %}
 {% endfor %}}

rest_framework/templates/rest_framework/docs/langs/python.html

@@ -6,7 +6,7 @@ client = coreapi.Client()
 schema = client.get("{{ document.url }}"{% if schema_format %}, format="{{ schema_format }}"{% endif %})
 
 # Interact with the API endpoint
-action = [{% if section_key %}"{{ section_key }}", {% endif %}"{{ link_key }}"]
+action = [{% for p in path %}"{{ p }}", {% endfor %}{% if section_key %}"{{ section_key }}", {% endif %}"{{ link_key }}"]
 {% if link.fields %}params = {
 {% for field in link.fields %}    "{{ field.name }}": ...{% if not loop.last %},{% endif %}
 {% endfor %}}

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

@@ -3,4 +3,4 @@
 $ coreapi get {{ document.url }}{% if schema_format %} --format {{ schema_format }}{% endif %}
 
 # Interact with the API endpoint
-$ coreapi action {% if section_key %}{{ section_key }} {% endif %}{{ link_key }}{% for field in link.fields %} -p {{ field.name }}=...{% endfor %}{% endcode %}</code></pre>
+$ coreapi action {% for p in path %}{{ p }} {% endfor %}{% if section_key %}{{ section_key }} {% endif %}{{ link_key }}{% for field in link.fields %} -p {{ field.name }}=...{% endfor %}{% endcode %}</code></pre>

rest_framework/templates/rest_framework/docs/link.html

@@ -10,8 +10,10 @@
         <i class="fa fa-exchange"></i> Interact
     </button>
 
-    <h3 id="{{ section_key }}-{{ link_key }}" class="coredocs-link-title">{{ link.title|default:link_key }} <a href="#{{ section_key }}-{{ link_key }}"><i class="fa fa-link" aria-hidden="true"></i>
-</a></h3>
+    <h3 id="{{ path|list_add:section_key|list_add:link_key|join:"-"|slugify }}" class="coredocs-link-title">
+        {{ link.title|default:link_key }}
+        <a href="#{{ path|list_add:section_key|list_add:link_key|join:"-"|slugify }}"><i class="fa fa-link" aria-hidden="true"></i></a>
+    </h3>
 
     <div class="meta">
         <span class="label label-primary">{{ link.action|upper }}</span>

rest_framework/templates/rest_framework/docs/sidebar.html

@@ -4,18 +4,7 @@
 
     <i class="fa fa-bars fa-2x toggle-btn" data-toggle="collapse" data-target="#menu-content"></i>
     <div class="menu-list">
-        <ul id="menu-content" class="menu-content collapse out">
-            {% for section_key, section in document.data|items %}
-            <li data-toggle="collapse" data-target="#{{ section_key }}-dropdown" class="collapsed">
-                <a><i class="fa fa-dot-circle-o fa-lg"></i> {% if section_key %}{{ section_key }}{% else %}API Endpoints{% endif %} <span class="arrow"></span></a>
-            </li>
-            <ul class="sub-menu {% if section_key %}collapse{% endif %}" id="{{ section_key }}-dropdown">
-                {% for link_key, link in section.links|items %}
-                    <li><a href="#{{ section_key }}-{{ link_key }}">{{ link.title|default:link_key }}</a></li>
-                {% endfor %}
-            </ul>
-            {% endfor %}
-        </ul>
+        {% include "rest_framework/docs/_recursive_menu.html" with items=document.data|items path=""|make_list %}
 
         <ul class="menu-list menu-list-bottom">
             <li data-toggle="collapse" data-target="#auth-control" class="collapsed">

rest_framework/templatetags/rest_framework.py

@@ -362,3 +362,17 @@ def break_long_headers(header):
     if len(header) > 160 and ',' in header:
         header = mark_safe('<br> ' + ', <br>'.join(header.split(',')))
     return header
+
+
+@register.filter
+def list_add(lst, item):
+    """
+    Appends a item to a list or a tuple. Original value is not modified.
+
+    Can be only applied to lists or tuples, raises TypeError otherwise.
+    """
+    if isinstance(lst, list):
+        return lst + [item]
+    elif isinstance(lst, tuple):
+        return lst + (item,)
+    raise TypeError("list_add only accepts lists or tuples")

tests/interactive_doc/data.py

@@ -0,0 +1,23 @@
+from django.db import models
+from rest_framework import serializers, viewsets
+from rest_framework.decorators import detail_route
+
+
+class DummyModel(models.Model):
+    pass
+
+
+class DummySerializer(serializers.ModelSerializer):
+
+    class Meta:
+        model = DummyModel
+        fields = ('id', )
+
+
+class DummyViewSet(viewsets.ModelViewSet):
+    serializer_class = DummySerializer
+    queryset = DummyModel.objects.all()
+
+    @detail_route(methods=['get', 'post'])
+    def retrieve_alt(self, request, *args, **kwargs):
+        return self.retrieve(request, *args, **kwargs)

tests/interactive_doc/test_recursive_url.py

@@ -0,0 +1,59 @@
+from __future__ import unicode_literals
+
+import re
+
+from django.test import TestCase, override_settings
+
+from rest_framework.test import APIClient
+
+
+@override_settings(ROOT_URLCONF='tests.interactive_doc.urls')
+class TestRecursiveUrlViewSets(TestCase):
+
+    def setUp(self):
+        client = APIClient()
+        response = client.get('/docs/')
+        self.content = response.content.decode('utf-8')
+
+    def test_menu(self):
+        self.assertTrue(
+            re.search('a href="#.*not_dummies\-list">', self.content),
+            'unable to find menu item for not_dummies'
+        )
+        for model_type in ['aaaa', 'bbbb']:
+            self.assertTrue(
+                re.search('a href="#.*{}s\-list">'.format(model_type), self.content),
+                'unable to find menu item for dummy/{}'.format(model_type)
+            )
+
+    def test_documentation(self):
+        header_re = 'h{level}\s+id="{path}".*>\s*{title}\s*<a href="#{path}"'
+
+        for route in (('not_dummies',), ('dummy', 'aaaas'), ('dummy', 'bbbbs')):
+            path = "-".join(route)
+            self.assertTrue(
+                re.search(header_re.format(level=1 + len(route), path=path, title=route[-1]), self.content),
+                'unable to find documentation section for {}'.format(path)
+            )
+            for method in ('read', 'create'):
+                subpath = "{}-retrieve_alt-{}".format(path, method)
+                self.assertTrue(
+                    re.search(header_re.format(level=3, path=subpath, title=method), self.content),
+                    'unable to find documentation section for {}'.format(subpath)
+                )
+                action_code = 'action = [{}, "retrieve_alt", "{}"]'.format(
+                    ", ".join('"{}"'.format(r) for r in route),
+                    method
+                )
+                self.assertTrue(
+                    action_code in self.content.replace('&quot;', '"'),
+                    'unable to find code snippet for {}'.format(subpath)
+                )
+                self.assertTrue(
+                    '$ coreapi action {} retrieve_alt {}'.format(' '.join(route), method) in self.content,
+                    'unable to find shell code snippet for {}'.format(subpath)
+                )
+                self.assertTrue(
+                    re.search('<li><a href="#{}"[^>]*>\s*{}'.format(subpath, method), self.content),
+                    'unable to find sidebar link for {}'.format(subpath)
+                )

tests/interactive_doc/urls.py

@@ -0,0 +1,18 @@
+from django.conf.urls import include, url
+
+from rest_framework.documentation import include_docs_urls
+from rest_framework.routers import DefaultRouter
+
+from .data import DummyViewSet
+
+
+router = DefaultRouter()
+
+router.register(r'dummy/aaaas', DummyViewSet)
+router.register(r'dummy/bbbbs', DummyViewSet)
+router.register(r'not_dummies', DummyViewSet)
+
+urlpatterns = [
+    url(r'', include(router.urls)),
+    url(r'^docs/', include_docs_urls())
+]