From f0e65d263767935a47cfa39ab89d538daee1e770 Mon Sep 17 00:00:00 2001
From: Aleksey Zhukov <drdaeman@drdaeman.pp.ru>
Date: Tue, 23 May 2017 18:22:02 +0300
Subject: [PATCH] Nested docs: use lists for paths instead of strings

This way we don't need to do any string manipulation (split_keys is gone),
and snippet code generation should be more flexible.
---
 .../docs/_recursive_document.html             | 15 +++++------
 .../rest_framework/docs/_recursive_menu.html  | 16 +++++-------
 .../rest_framework/docs/document.html         |  4 +--
 .../rest_framework/docs/interact.html         |  2 +-
 .../rest_framework/docs/langs/javascript.html |  2 +-
 .../rest_framework/docs/langs/python.html     |  2 +-
 .../rest_framework/docs/langs/shell.html      |  2 +-
 .../templates/rest_framework/docs/link.html   |  6 +++--
 .../rest_framework/docs/sidebar.html          |  2 +-
 rest_framework/templatetags/rest_framework.py | 25 ++++++++-----------
 tests/interactive_doc/test_recursive_url.py   |  6 ++---
 11 files changed, 38 insertions(+), 44 deletions(-)

diff --git a/rest_framework/templates/rest_framework/docs/_recursive_document.html b/rest_framework/templates/rest_framework/docs/_recursive_document.html
index d1596b454..fcdbf5c80 100644
--- a/rest_framework/templates/rest_framework/docs/_recursive_document.html
+++ b/rest_framework/templates/rest_framework/docs/_recursive_document.html
@@ -1,15 +1,16 @@
 {% load rest_framework %}
 {% for section_key, section in items %}
-{% if section_key %}
-  <h{{level}} id="{{prefix}}{{ section_key }}" class="coredocs-section-title">{{ section_key }} <a href="#{{ prefix }}{{ section_key }}"><i class="fa fa-link" aria-hidden="true"></i>
-  </a></h{{level}}>
-{% endif %}
+    {% if section_key %}
+        <h{{level}} id="{{ path|list_add:section_key|join:'-' }}" class="coredocs-section-title">
+            {{ section_key }}
+            <a href="#{{ path|list_add:section_key|join:'-' }}"><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 prefix=prefix level=level|add:1%}
+            {% include "rest_framework/docs/link.html" with path=path %}
         {% endfor %}
     {% endif %}
-    {% include 'rest_framework/docs/_recursive_document.html' with items=section.data|items prefix=prefix|add:section_key|add:'/' level=level|add:1 %}
+    {% include 'rest_framework/docs/_recursive_document.html' with items=section.data|items path=path|list_add:section_key level=level|add:1 %}
 {% endfor %}
-
diff --git a/rest_framework/templates/rest_framework/docs/_recursive_menu.html b/rest_framework/templates/rest_framework/docs/_recursive_menu.html
index 82775dd02..bb86a87c5 100644
--- a/rest_framework/templates/rest_framework/docs/_recursive_menu.html
+++ b/rest_framework/templates/rest_framework/docs/_recursive_menu.html
@@ -1,22 +1,18 @@
 {% load rest_framework %}
 {% if items %}
-<ul id="{% if prefix %}{{prefix}}-dropdown{% else %}menu-content{% endif %}" class="menu-content collapse out">
+<ul id="{% if path %}{{ path|join:"-" }}-dropdown{% else %}menu-content{% endif %}" class="menu-content collapse out">
     {% for section_key, section in items %}
-        <li data-toggle="collapse" data-target="#{{prefix}}{{ section_key }}-dropdown" class="collapsed">
-          <a><i class="fa fa-dot-circle-o fa-lg"></i> {% if prefix %}{{prefix}}/{% endif %}{% if section_key %}{{ section_key }}{% else %}API Endpoints{% endif %} <span class="arrow"></span></a>
+        <li data-toggle="collapse" data-target="#{{ path|list_add:section_key|join:"-" }}-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="{{prefix}}{{ section_key }}-dropdown">
+            <ul class="sub-menu {% if section_key %}collapse{% endif %}" id="{{ path|list_add:section_key|join:'-' }}-dropdown">
                 {% for link_key, link in section.links|items %}
-                <li><a href="#{% if prefix %}{{prefix}}/{% endif %}{{ section_key }}-{{ link_key }}">{{ link.title|default:link_key }}</a></li>
+                <li><a href="#{{ path|list_add:section_key|list_add:link_key|join:"-" }}">{{ link.title|default:link_key }}</a></li>
                 {% endfor %}
             </ul>
         {% endif %}
-        {% if prefix %}
-            {% include 'rest_framework/docs/_recursive_menu.html' with items=section.data|items prefix=prefix|add:'/'|add:section_key %}
-        {% else %}
-            {% include 'rest_framework/docs/_recursive_menu.html' with items=section.data|items prefix=section_key %}
-        {% endif %}
+        {% include "rest_framework/docs/_recursive_menu.html" with items=section.data|items path=path|list_add:section_key %}
     {% endfor %}
 </ul>
 {% endif %}
diff --git a/rest_framework/templates/rest_framework/docs/document.html b/rest_framework/templates/rest_framework/docs/document.html
index 5a3948d17..2faf375e2 100644
--- a/rest_framework/templates/rest_framework/docs/document.html
+++ b/rest_framework/templates/rest_framework/docs/document.html
@@ -14,8 +14,8 @@
 </div>
 </div>
 
-{% include 'rest_framework/docs/_recursive_document.html' with items=document.data|items level=2 %}
+{% 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 %}
diff --git a/rest_framework/templates/rest_framework/docs/interact.html b/rest_framework/templates/rest_framework/docs/interact.html
index 4d2f8b063..c7211c6c9 100644
--- a/rest_framework/templates/rest_framework/docs/interact.html
+++ b/rest_framework/templates/rest_framework/docs/interact.html
@@ -16,7 +16,7 @@
 
     </div>
 
-    <form data-key='[{{ prefix|split_keys }} "{{ 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">
diff --git a/rest_framework/templates/rest_framework/docs/langs/javascript.html b/rest_framework/templates/rest_framework/docs/langs/javascript.html
index a5d33d589..c4b304ea5 100644
--- a/rest_framework/templates/rest_framework/docs/langs/javascript.html
+++ b/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 = [{{ prefix|split_keys }}{% 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 %}}
diff --git a/rest_framework/templates/rest_framework/docs/langs/python.html b/rest_framework/templates/rest_framework/docs/langs/python.html
index 0951c0fb4..62ba42e05 100644
--- a/rest_framework/templates/rest_framework/docs/langs/python.html
+++ b/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 = [{{ prefix|split_keys }}{% 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 %}}
diff --git a/rest_framework/templates/rest_framework/docs/langs/shell.html b/rest_framework/templates/rest_framework/docs/langs/shell.html
index 37f26ee02..a3b95d63d 100644
--- a/rest_framework/templates/rest_framework/docs/langs/shell.html
+++ b/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 {{ prefix|split_keys:'cmd' }}{% 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>
diff --git a/rest_framework/templates/rest_framework/docs/link.html b/rest_framework/templates/rest_framework/docs/link.html
index 993d9e3d9..dd5413f0d 100644
--- a/rest_framework/templates/rest_framework/docs/link.html
+++ b/rest_framework/templates/rest_framework/docs/link.html
@@ -10,8 +10,10 @@
         <i class="fa fa-exchange"></i> Interact
     </button>
 
-    <h3 id="{{prefix}}{{ section_key }}-{{ link_key }}" class="coredocs-link-title">{{ link.title|default:link_key }} <a href="#{{prefix}}{{ 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:"-" }}" class="coredocs-link-title">
+        {{ link.title|default:link_key }}
+        <a href="#{{ path|list_add:section_key|list_add:link_key|join:"-" }}"><i class="fa fa-link" aria-hidden="true"></i></a>
+    </h3>
 
     <div class="meta">
         <span class="label label-primary">{{ link.action|upper }}</span>
diff --git a/rest_framework/templates/rest_framework/docs/sidebar.html b/rest_framework/templates/rest_framework/docs/sidebar.html
index 788076d45..0bc25e385 100644
--- a/rest_framework/templates/rest_framework/docs/sidebar.html
+++ b/rest_framework/templates/rest_framework/docs/sidebar.html
@@ -4,7 +4,7 @@
 
     <i class="fa fa-bars fa-2x toggle-btn" data-toggle="collapse" data-target="#menu-content"></i>
     <div class="menu-list">
-        {% include 'rest_framework/docs/_recursive_menu.html' with items=document.data|items %}
+        {% 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">
diff --git a/rest_framework/templatetags/rest_framework.py b/rest_framework/templatetags/rest_framework.py
index 10a8cffb1..aae6a5950 100644
--- a/rest_framework/templatetags/rest_framework.py
+++ b/rest_framework/templatetags/rest_framework.py
@@ -365,19 +365,14 @@ def break_long_headers(header):
 
 
 @register.filter
-def split_keys(keys, cmd_type='script'):
-    if not keys:
-        return ''
+def list_add(lst, item):
+    """
+    Appends a item to a list or a tuple. Original value is not modified.
 
-    if cmd_type == 'script':
-        joiner = ', '
-        wrapper = '"'
-    else:
-        joiner = ' '
-        wrapper = ''
-
-    return joiner.join([
-        '{wrapper}{k}{wrapper}'.format(k=k, wrapper=wrapper)
-        if k != '' else ''
-        for k in keys.split('/')
-    ])
+    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")
diff --git a/tests/interactive_doc/test_recursive_url.py b/tests/interactive_doc/test_recursive_url.py
index 9dd54a991..ef6f86f22 100644
--- a/tests/interactive_doc/test_recursive_url.py
+++ b/tests/interactive_doc/test_recursive_url.py
@@ -27,16 +27,16 @@ class TestRecursiveUrlViewSets(TestCase):
             )
 
     def test_documentation(self):
-        header_re = 'h{level}\s+id="{path}".*>{title} <a href="#{path}"'
+        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)
+            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)
+                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)