Display docs for each namespace

rest_framework_docs/api_docs.py

@@ -1,3 +1,4 @@
+from operator import attrgetter
 from django.conf import settings
 from django.core.urlresolvers import RegexURLResolver, RegexURLPattern
 from rest_framework.views import APIView
@@ -6,25 +7,34 @@
 
 class ApiDocumentation(object):
 
-    def __init__(self):
+    def __init__(self, filter_app=None):
+        """
+        :param filter_app: namespace or app_name
+        """
         self.endpoints = []
         root_urlconf = __import__(settings.ROOT_URLCONF)
         if hasattr(root_urlconf, 'urls'):
-            self.get_all_view_names(root_urlconf.urls.urlpatterns)
+            self.get_all_view_names(root_urlconf.urls.urlpatterns, filter_app=filter_app)
         else:
-            self.get_all_view_names(root_urlconf.urlpatterns)
+            self.get_all_view_names(root_urlconf.urlpatterns, filter_app=filter_app)
 
-    def get_all_view_names(self, urlpatterns, parent_pattern=None):
+    def get_all_view_names(self, urlpatterns, parent_pattern=None, filter_app=None):
         for pattern in urlpatterns:
-            if isinstance(pattern, RegexURLResolver):
-                self.get_all_view_names(urlpatterns=pattern.url_patterns, parent_pattern=pattern)
+            if isinstance(pattern, RegexURLResolver) and (not filter_app or filter_app in [pattern.app_name, pattern.namespace]):
+                self.get_all_view_names(urlpatterns=pattern.url_patterns, parent_pattern=pattern, filter_app=filter_app)
             elif isinstance(pattern, RegexURLPattern) and self._is_drf_view(pattern):
-                api_endpoint = ApiEndpoint(pattern, parent_pattern)
-                self.endpoints.append(api_endpoint)
+                if not filter_app or (parent_pattern and filter_app in [parent_pattern.app_name, parent_pattern.namespace]):
+                    api_endpoint = ApiEndpoint(pattern, parent_pattern)
+                    self.endpoints.append(api_endpoint)
 
     def _is_drf_view(self, pattern):
-        # Should check whether a pattern inherits from DRF's APIView
+        """
+        Should check whether a pattern inherits from DRF's APIView
+        """
         return hasattr(pattern.callback, 'cls') and issubclass(pattern.callback.cls, APIView)
 
     def get_endpoints(self):
-        return self.endpoints
+        """
+        Returns the endpoints sorted by the app name
+        """
+        return sorted(self.endpoints, key=attrgetter('name'))

rest_framework_docs/api_endpoint.py

@@ -1,27 +1,37 @@
 import json
 import inspect
 from django.contrib.admindocs.views import simplify_regex
+from rest_framework.viewsets import ModelViewSet
 
 
 class ApiEndpoint(object):
 
     def __init__(self, pattern, parent_pattern=None):
         self.pattern = pattern
         self.callback = pattern.callback
-        # self.name = pattern.name
         self.docstring = self.__get_docstring__()
-        self.name_parent = simplify_regex(parent_pattern.regex.pattern).replace('/', '') if parent_pattern else None
+
+        if parent_pattern:
+            self.name_parent = parent_pattern.namespace or parent_pattern.app_name or \
+                simplify_regex(parent_pattern.regex.pattern).replace('/', '-')
+            self.name = self.name_parent
+            if hasattr(pattern.callback, 'cls') and issubclass(pattern.callback.cls, ModelViewSet):
+                self.name = '%s (REST)' % self.name_parent
+        else:
+            self.name_parent = ''
+            self.name = ''
+
+        self.labels = dict(parent=self.name_parent, name=self.name)
         self.path = self.__get_path__(parent_pattern)
         self.allowed_methods = self.__get_allowed_methods__()
-        # self.view_name = pattern.callback.__name__
         self.errors = None
         self.fields = self.__get_serializer_fields__()
         self.fields_json = self.__get_serializer_fields_json__()
         self.permissions = self.__get_permissions_class__()
 
     def __get_path__(self, parent_pattern):
         if parent_pattern:
-            return "/{0}{1}".format(self.name_parent, simplify_regex(self.pattern.regex.pattern))
+            return simplify_regex(parent_pattern.regex.pattern + self.pattern.regex.pattern)
         return simplify_regex(self.pattern.regex.pattern)
 
     def __get_allowed_methods__(self):

rest_framework_docs/templates/rest_framework_docs/home.html

@@ -1,86 +1,91 @@
 {% extends "rest_framework_docs/docs.html" %}
 
 {% block apps_menu %}
-{% regroup endpoints by name_parent as endpoints_grouped %}
-<li class="dropdown">
-  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Jump To <span class="caret"></span></a>
-  <ul class="dropdown-menu">
-    {% for group in endpoints_grouped %}
-      <li><a href="#{{ group.grouper|lower }}-group">{{ group.grouper }}</a></li>
-    {% endfor %}
-  </ul>
-</li>
+  {% regroup endpoints by labels as endpoints_grouped %}
+
+  {% if endpoints_grouped|length > 1 %}
+    <li class="dropdown">
+      <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Jump To <span class="caret"></span></a>
+      <ul class="dropdown-menu">
+        {% for group in endpoints_grouped %}
+          <li><a href="#{{ group.grouper.name|slugify }}-group">{{ group.grouper.name }}</a></li>
+        {% endfor %}
+      </ul>
+    </li>
+  {% endif %}
 {% endblock %}
 
 
 {% block content %}
-
-  {% regroup endpoints by name_parent as endpoints_grouped %}
+  {% regroup endpoints by labels as endpoints_grouped %}
 
   {% if endpoints_grouped %}
-  {% for group in endpoints_grouped %}
-
-    <h1 id="{{ group.grouper|lower }}-group">{{group.grouper}}</h1>
-
-    <div class="panel-group" role="tablist">
-
-    {% for endpoint in group.list %}
-
-      <div class="panel panel-default endpoint">
-
-        <div class="panel-heading" role="tab" data-toggle="collapse" data-target="#{{ endpoint.path|slugify }}">
-          <div class="row">
-            <div class="col-md-7">
-              <h4 class="panel-title title">
-                <i class="fa fa-link"></i> {{ endpoint.path }}
-              </h4>
+    {% for group in endpoints_grouped %}
+      <h1 id="{{ group.grouper.name|slugify }}-group">
+        {% if group.grouper.parent %}
+          <a href="{% url 'drfdocs-filter' group.grouper.parent %}">{{ group.grouper.name }}</a>
+        {% endif %}
+      </h1>
+
+      <div class="panel-group" role="tablist">
+
+      {% for endpoint in group.list %}
+
+        <div class="panel panel-default endpoint">
+
+          <div class="panel-heading" role="tab" data-toggle="collapse" data-target="#{{ endpoint.path|slugify }}">
+            <div class="row">
+              <div class="col-md-7">
+                <h4 class="panel-title title">
+                  <i class="fa fa-link"></i> {{ endpoint.path }}
+                </h4>
+              </div>
+
+              <div class="col-md-5">
+                <ul class="list-inline methods">
+                  {% for method in endpoint.allowed_methods %}
+                    <li class="method {{ method|lower }}">{{ method }}</li>
+                  {% endfor %}
+                    <li class="method plug"
+                      data-toggle="modal"
+                      data-path="{{ endpoint.path }}"
+                      data-methods="{{ endpoint.allowed_methods }}"
+                      data-permissions="{{ endpoint.permissions }}"
+                      data-fields="{{ endpoint.fields_json }}">
+                      <i class="fa fa-plug"></i></li>
+                </ul>
+              </div>
             </div>
+          </div>
 
-            <div class="col-md-5">
-              <ul class="list-inline methods">
-                {% for method in endpoint.allowed_methods %}
-                  <li class="method {{ method|lower }}">{{ method }}</li>
+          <div id="{{ endpoint.path|slugify }}" class="panel-collapse collapse" role="tabpanel">
+            <div class="panel-body">
+              {% if endpoint.docstring %}
+              <p class="lead">{{ endpoint.docstring }}</p>
+              {% endif %}
+
+              {% if endpoint.errors %}
+              <div class="alert alert-danger" role="alert">Oops! There was something wrong with {{ endpoint.errors }}. Please check your code.</div>
+              {% endif %}
+
+              {% if endpoint.fields %}
+              <p class="fields-desc">Fields:</p>
+                <ul class="list fields">
+                {% for field in endpoint.fields %}
+                  <li class="field">{{ field.name }}: {{ field.type }} {% if field.required %}<span class="label label-primary label-required" title="Required">R</span>{% endif %}</li>
                 {% endfor %}
-                  <li class="method plug"
-                    data-toggle="modal"
-                    data-path="{{ endpoint.path }}"
-                    data-methods="{{ endpoint.allowed_methods }}"
-                    data-permissions="{{ endpoint.permissions }}"
-                    data-fields="{{ endpoint.fields_json }}">
-                    <i class="fa fa-plug"></i></li>
-              </ul>
+                </ul>
+              {% elif not endpoint.errors %}
+              <p>No fields.</p>
+              {% endif %}
             </div>
           </div>
         </div>
+      {% endfor %}
 
-        <div id="{{ endpoint.path|slugify }}" class="panel-collapse collapse" role="tabpanel">
-          <div class="panel-body">
-            {% if endpoint.docstring %}
-            <p class="lead">{{ endpoint.docstring }}</p>
-            {% endif %}
-
-            {% if endpoint.errors %}
-            <div class="alert alert-danger" role="alert">Oops! There was something wrong with {{ endpoint.errors }}. Please check your code.</div>
-            {% endif %}
-
-            {% if endpoint.fields %}
-            <p class="fields-desc">Fields:</p>
-              <ul class="list fields">
-              {% for field in endpoint.fields %}
-                <li class="field">{{ field.name }}: {{ field.type }} {% if field.required %}<span class="label label-primary label-required" title="Required">R</span>{% endif %}</li>
-              {% endfor %}
-              </ul>
-            {% elif not endpoint.errors %}
-            <p>No fields.</p>
-            {% endif %}
-          </div>
-        </div>
       </div>
-    {% endfor %}
-
-    </div>
 
-  {% endfor %}
+    {% endfor %}
   {% elif not query %}
     <h2 class="text-center">There are currently no api endpoints to document.</h2>
   {% else %}

rest_framework_docs/urls.py

@@ -4,4 +4,7 @@
 urlpatterns = [
     # Url to view the API Docs
     url(r'^$', DRFDocsView.as_view(), name='drfdocs'),
+
+    # Url to view the API Docs with a specific namespace or app_name
+    url(r'^(?P<filter_app>[\w-]+)/$', DRFDocsView.as_view(), name='drfdocs-filter'),
 ]

rest_framework_docs/views.py

@@ -10,17 +10,22 @@ class DRFDocsView(TemplateView):
 
     def get_context_data(self, **kwargs):
         settings = DRFSettings().settings
+        search_query = self.request.GET.get("search", "")
+        filter_app = self.kwargs.get("filter_app", None)
+
         if settings["HIDE_DOCS"]:
             raise Http404("Django Rest Framework Docs are hidden. Check your settings.")
 
-        context = super(DRFDocsView, self).get_context_data(**kwargs)
-        docs = ApiDocumentation()
+        docs = ApiDocumentation(filter_app=filter_app)
         endpoints = docs.get_endpoints()
 
-        query = self.request.GET.get("search", "")
-        if query and endpoints:
-            endpoints = [endpoint for endpoint in endpoints if query in endpoint.path]
+        if filter_app and not endpoints:
+            raise Http404("The are no endpoints for \"%s\"." % filter_app)
 
-        context['query'] = query
+        if search_query and endpoints:
+            endpoints = [endpoint for endpoint in endpoints if search_query in endpoint.path]
+
+        context = super(DRFDocsView, self).get_context_data(**kwargs)
+        context['query'] = search_query
         context['endpoints'] = endpoints
         return context

runtests.py

@@ -53,6 +53,7 @@ def run_tests_coverage():
         cov.report()
         cov.html_report(directory='covhtml')
 
+
 exit_on_failure(flake8_main(FLAKE8_ARGS))
 exit_on_failure(run_tests_eslint())
 exit_on_failure(run_tests_coverage())

tests/tests.py

@@ -19,7 +19,7 @@ def test_settings_module(self):
         self.assertEqual(settings.get_setting("HIDE_DOCS"), False)
         self.assertEqual(settings.get_setting("TEST"), None)
 
-    def test_index_view_with_endpoints(self):
+    def test_docs_home_view_with_endpoints(self):
         """
         Should load the drf focs view with all the endpoints.
         NOTE: Views that do **not** inherit from DRF's "APIView" are not included.
@@ -30,16 +30,16 @@ def test_index_view_with_endpoints(self):
         self.assertEqual(len(response.context["endpoints"]), 10)
 
         # Test the login view
-        self.assertEqual(response.context["endpoints"][0].name_parent, "accounts")
-        self.assertEqual(response.context["endpoints"][0].allowed_methods, ['POST', 'OPTIONS'])
-        self.assertEqual(response.context["endpoints"][0].path, "/accounts/login/")
-        self.assertEqual(response.context["endpoints"][0].docstring, "A view that allows users to login providing their username and password.")
-        self.assertEqual(len(response.context["endpoints"][0].fields), 2)
-        self.assertEqual(response.context["endpoints"][0].fields[0]["type"], "CharField")
-        self.assertTrue(response.context["endpoints"][0].fields[0]["required"])
+        self.assertEqual(response.context["endpoints"][1].name_parent, "accounts")
+        self.assertEqual(response.context["endpoints"][1].allowed_methods, ['POST', 'OPTIONS'])
+        self.assertEqual(response.context["endpoints"][1].path, "/accounts/login/")
+        self.assertEqual(response.context["endpoints"][1].docstring, "A view that allows users to login providing their username and password.")
+        self.assertEqual(len(response.context["endpoints"][1].fields), 2)
+        self.assertEqual(response.context["endpoints"][1].fields[0]["type"], "CharField")
+        self.assertTrue(response.context["endpoints"][1].fields[0]["required"])
 
         # The view "OrganisationErroredView" (organisations/(?P<slug>[\w-]+)/errored/) should contain an error.
-        self.assertEqual(str(response.context["endpoints"][8].errors), "'test_value'")
+        self.assertEqual(str(response.context["endpoints"][9].errors), "'test_value'")
 
     def test_index_search_with_endpoints(self):
         response = self.client.get("%s?search=reset-password" % reverse("drfdocs"))
@@ -59,3 +59,68 @@ def test_index_view_docs_hidden(self):
 
         self.assertEqual(response.status_code, 404)
         self.assertEqual(response.reason_phrase.upper(), "NOT FOUND")
+
+    def test_index_view_with_existent_namespace(self):
+        """
+        Should load the drf docs view with all the endpoints contained in the specified namespace.
+        NOTE: Views that do **not** inherit from DRF's "APIView" are not included.
+        """
+        # Test 'accounts' namespace
+        response = self.client.get(reverse('drfdocs-filter', args=['accounts']))
+        # response = self.client.get(reverse('drfdocs-filter', kwargs={'parent_app': 'accountss'}))
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 5)
+
+        # Test the login view
+        self.assertEqual(response.context["endpoints"][0].name_parent, "accounts")
+        self.assertEqual(response.context["endpoints"][0].allowed_methods, ['POST', 'OPTIONS'])
+        self.assertEqual(response.context["endpoints"][0].path, "/accounts/login/")
+
+        # Test 'organisations' namespace
+        response = self.client.get(reverse('drfdocs-filter', args=['organisations']))
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 3)
+
+        # The view "OrganisationErroredView" (organisations/(?P<slug>[\w-]+)/errored/) should contain an error.
+        self.assertEqual(str(response.context["endpoints"][2].errors), "'test_value'")
+
+        # Test 'members' namespace
+        response = self.client.get(reverse('drfdocs-filter', args=['members']))
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 1)
+
+    def test_index_search_with_existent_namespace(self):
+        response = self.client.get("%s?search=reset-password" % reverse('drfdocs-filter', args=['accounts']))
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 2)
+        self.assertEqual(response.context["endpoints"][1].path, "/accounts/reset-password/confirm/")
+        self.assertEqual(len(response.context["endpoints"][1].fields), 3)
+
+    def test_index_view_with_existent_app_name(self):
+        """
+        Should load the drf docs view with all the endpoints contained in the specified app_name.
+        NOTE: Views that do **not** inherit from DRF's "APIView" are not included.
+        """
+        # Test 'organisations_app' app_name
+        response = self.client.get(reverse('drfdocs-filter', args=['organisations_app']))
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 4)
+        parents_name = [e.name_parent for e in response.context["endpoints"]]
+        self.assertEquals(parents_name.count('organisations'), 3)
+        self.assertEquals(parents_name.count('members'), 1)
+
+    def test_index_search_with_existent_app_name(self):
+        response = self.client.get("%s?search=create" % reverse('drfdocs-filter', args=['organisations_app']))
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(len(response.context["endpoints"]), 1)
+        self.assertEqual(response.context["endpoints"][0].path, "/organisations/create/")
+        self.assertEqual(len(response.context["endpoints"][0].fields), 2)
+
+    def test_index_view_with_non_existent_namespace_or_app_name(self):
+        """
+        Should raise a 404 if there is no such app name like the param.
+        """
+        response = self.client.get(reverse('drfdocs-filter', args=['non-existent-ns-or-app-name']))
+        self.assertEqual(response.status_code, 404)