Merge pull request #20 from ekonstantinidis/get-docstrings

Get docstrings of endpoints

Author: ekonstantinidis

demo/project/accounts/views.py

@@ -20,6 +20,9 @@ class TestView(TemplateView):
 
 
 class LoginView(APIView):
+    """
+    A view that allows users to login providing their username and password.
+    """
 
     throttle_classes = ()
     permission_classes = ()
@@ -42,6 +45,9 @@ class UserRegistrationView(generics.CreateAPIView):
 
 
 class UserProfileView(generics.RetrieveUpdateAPIView):
+    """
+    An endpoint for users to view and update their profile information.
+    """
 
     serializer_class = UserProfileSerializer
 

rest_framework_docs/api_endpoint.py

@@ -1,3 +1,4 @@
+import inspect
 from django.contrib.admindocs.views import simplify_regex
 
 
@@ -7,6 +8,7 @@ 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
         self.path = self.__get_path__(parent_pattern)
         self.allowed_methods = self.__get_allowed_methods__()
@@ -22,6 +24,9 @@ def __get_path__(self, parent_pattern):
     def __get_allowed_methods__(self):
         return [m.upper() for m in self.callback.cls.http_method_names if hasattr(self.callback.cls, m)]
 
+    def __get_docstring__(self):
+        return inspect.getdoc(self.callback)
+
     def __get_serializer_fields__(self):
         fields = []
 

rest_framework_docs/static/css/style.css

@@ -92,10 +92,22 @@ body {
   .panel-body {
     padding: 0;
 
+    .lead {
+      margin-bottom: 5px;
+    }
+
     .alert {
       padding: 5px 10px;
       margin-top: 10px;
     }
+
+    .fields-desc {
+      margin-bottom: 5px;
+    }
+
+    .fields {
+      list-style-type: square;
+    }
   }
 
   > .panel-heading +.panel-collapse > .panel-body { border: 0; }

rest_framework_docs/static/less/style.less

@@ -20,8 +20,7 @@
     "django",
     "rest",
     "framework",
-    "docs",
-    "jekyll"
+    "docs"
   ],
   "author": "Emmanouil Konstantinidis",
   "license": "SEE LICENSE IN LICENSE",

rest_framework_docs/static/package.json

@@ -48,12 +48,16 @@ <h4 class="panel-title title">
 
         <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>Fields:</p>
+            <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>

rest_framework_docs/templates/rest_framework_docs/home.html

@@ -33,6 +33,7 @@ def test_index_view_with_endpoints(self):
         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"])

tests/tests.py

@@ -20,6 +20,9 @@ class TestView(TemplateView):
 
 
 class LoginView(APIView):
+    """
+    A view that allows users to login providing their username and password.
+    """
 
     throttle_classes = ()
     permission_classes = ()
@@ -42,6 +45,9 @@ class UserRegistrationView(generics.CreateAPIView):
 
 
 class UserProfileView(generics.RetrieveUpdateAPIView):
+    """
+    An endpoint for users to view and update their profile information.
+    """
 
     serializer_class = serializers.UserProfileSerializer