Adds comments in the code to make it easier to understand

Improves caching for apidoc files

Author: viniciuschiele

flask_apidoc/apidoc.py

@@ -17,14 +17,24 @@
 
 from flask import request
 from functools import lru_cache
-from os.path import join
-from os.path import getmtime
-from os.path import getsize
+from os.path import join, getmtime, getsize
 from werkzeug.datastructures import Headers
 
 
 class ApiDoc(object):
+    """
+    ApiDoc hosts the apidoc files in a specified url.
+    """
+
     def __init__(self, folder_path=None, url_path=None, app=None):
+        """
+        Initializes a new instance of ApiDoc.
+
+        :param folder_path: the folder with apidoc files. Defaults to the 'docs' folder in the flask static folder.
+        :param url_path: the url path for the apidoc files. Defaults to the '/docs'.
+        :param app: the flask application.
+        """
+
         self.folder_path = folder_path
         self.url_path = url_path
 
@@ -40,6 +50,11 @@ def __init__(self, folder_path=None, url_path=None, app=None):
             self.init_app(app)
 
     def init_app(self, app):
+        """
+        Adds the flask url routes for the apidoc files.
+        :param app: the flask application.
+        """
+
         self.app = app
 
         url = self.url_path
@@ -50,36 +65,49 @@ def init_app(self, app):
         app.add_url_rule(url, 'docs', self.__send_static_file, strict_slashes=True)
         app.add_url_rule(url + '<path:path>', 'docs', self.__send_static_file, strict_slashes=True)
 
-    @lru_cache()
-    def __get_project_info(self):
-        file_name = join(self.app.static_folder, self.folder_path, 'api_project.json')
-
-        with open(file_name, 'rt') as file:
-            data = file.read()
-
-        return json.loads(data)
-
     def __send_static_file(self, path=None):
+        """
+        Sends apidoc files from the apidoc folder to the browser.
+        :param path: the apidoc file
+        """
+
         if not path:
             path = 'index.html'
 
         file_name = join(self.folder_path, path)
 
+        # Both api_project.js and api_data.js have the absolute url
+        # hard coded so we replace them by the current url.
         if path == 'api_project.js' or path == 'api_data.js':
             return self.__send_api_file(file_name)
 
+        # Any other apidoc file is treated as a normal static file
         return self.app.send_static_file(file_name)
 
-    @lru_cache(maxsize=1048576)
+    @lru_cache(maxsize=None, typed=True)
     def __send_api_file(self, file_name):
+        """
+        Sends apidoc files from the apidoc folder to the browser.
+        This method replaces all absolute urls in the file by
+        the current url.
+        :param file_name: the apidoc file
+        """
+
         file_name = join(self.app.static_folder, file_name)
 
         with open(file_name, 'rt') as file:
             data = file.read()
 
-        project_info = self.__get_project_info()
+        # replaces the hard coded url by the
+        # current url.
+        api_project = self.__read_api_project()
+
+        new_url = request.url_root.strip('/')
+        old_url = api_project.get('url')
+        data = data.replace(old_url, new_url)
 
-        data = self.__replace_url(data, project_info.get('url'), request.url_root)
+        # creates a flask response to send
+        # the file to the browser
 
         headers = Headers()
         headers['Content-Length'] = getsize(file_name)
@@ -93,7 +121,16 @@ def __send_api_file(self, file_name):
 
         return response
 
-    @staticmethod
-    def __replace_url(data, old_url, new_url):
-        new_url = new_url.strip('/')
-        return data.replace(old_url, new_url)
+    @lru_cache(maxsize=None)
+    def __read_api_project(self):
+        """
+        Reads the api_project.json file from apidoc folder as a json string.
+        :return: a json string
+        """
+
+        file_name = join(self.app.static_folder, self.folder_path, 'api_project.json')
+
+        with open(file_name, 'rt') as file:
+            data = file.read()
+
+        return json.loads(data)

flask_apidoc/commands.py

@@ -25,6 +25,10 @@
 
 
 class GenerateApiDoc(Command):
+    """
+    GenerateApiDoc adds to Flask-Script a command to generate the apidoc files.
+    """
+
     def __init__(self, input_path=None, output_path=None, template_path=None):
         super().__init__()
         self.input_path = input_path