Remove superfluous docstrings and change them to comments which are more intelligently positioned in the code.

Author: krinsman

nbviewer/providers/base.py

@@ -57,6 +57,8 @@ class BaseHandler(web.RequestHandler):
     """Base Handler class with common utilities"""
 
     def initialize(self, format=None, format_prefix="", **handler_settings):
+        # format: str, optional
+        #     Rendering format (e.g. script, slides, html)
         self.format = format or self.default_format
         self.format_prefix = format_prefix
         self.http_client = httpclient.AsyncHTTPClient()
@@ -631,20 +633,34 @@ def filter_formats(self, nb, raw):
                 app_log.info("failed to test %s: %s", self.request.uri, name)
 
     # empty methods to be implemented by subclasses to make GET requests more modular
-    def format_notebook_request(self, **kwargs):
+    def get_notebook_data(self, **kwargs):
+        """
+        Pass as kwargs variables needed to define those variables which will be necessary for 
+        the provider to find the notebook. (E.g. path for LocalHandler, user and repo for GitHub.) 
+        Return variables the provider needs to find and load the notebook. Then run custom logic
+        in GET or pass the output of get_notebook_data immediately to deliver_notebook.
+
+        First part of any provider's GET method. 
+
+        Custom logic, if applicable, is middle part of any provider's GET method, and usually
+        is implemented or overwritten in subclasses, while get_notebook_data and deliver_notebook
+        will often remain unchanged from the parent class (e.g. for a custom GitHub provider).
+        """
         pass
 
-    def load_notebook(self, **kwargs):
+    def deliver_notebook(self, **kwargs):
+        """
+        Pass as kwargs the return values of get_notebook_data to this method. Get the JSON data
+        from the provider to render the notebook. Finish with a call to self.finish_notebook.
+
+        Last part of any provider's GET method.
+        """
         pass 
 
     # Wrappers to facilitate custom rendering in subclasses without having to rewrite entire GET methods
     # This would seem to mostly involve creating different template namespaces to enable custom logic in
     # extended templates, but there might be other possibilities
     def render_notebook_template(self, body, nb, download_url, json_notebook, **namespace):
-        """
-        format: str, optional
-            Rendering format (e.g., script, slides, html)
-        """    
         return self.render_template(
             "formats/%s.html" % self.format,
             body=body,

nbviewer/providers/gist/handlers.py

@@ -24,16 +24,18 @@
 from .. import _load_handler_from_location
 
 class GistClientMixin(GithubClientMixin):
-    """
-    provider_label: str
-        Text to to apply to the navbar icon linking to the provider
-    provider_icon: str
-        CSS classname to apply to the navbar icon linking to the provider
-    executor_label: str, optional
-        Text to apply to the navbar icon linking to the execution service
-    executor_icon: str, optional
-        CSS classname to apply to the navbar icon linking to the execution service
-    """
+    
+    # PROVIDER_CTX is a dictionary whose entries are passed as keyword arguments
+    # to the render_template method of the GistHandler. The following describe
+    # the information contained in each of these keyword arguments:
+    # provider_label: str
+    #     Text to to apply to the navbar icon linking to the provider
+    # provider_icon: str
+    #     CSS classname to apply to the navbar icon linking to the provider
+    # executor_label: str, optional
+    #     Text to apply to the navbar icon linking to the execution service
+    # executor_icon: str, optional
+    #     CSS classname to apply to the navbar icon linking to the execution service
     PROVIDER_CTX = {
         'provider_label': 'Gist',
         'provider_icon': 'github-square',
@@ -63,7 +65,7 @@ def render_usergists_template(self, entries, user, provider_url, prev_url,
         """
         provider_url: str
             URL to the notebook document upstream at the provider (e.g., GitHub)
-        executor_url: str, optional
+        executor_url: str, optional (kwarg passed into `namespace`)
             URL to execute the notebook document (e.g., Binder)
         """
         return self.render_template("usergists.html", entries=entries, user=user,
@@ -139,10 +141,7 @@ def parse_gist(self, user, gist_id, filename=''):
     @gen.coroutine
     def tree_get(self, user, gist_id, gist, files):
         """
-        provider_url:
-            URL to the notebook document upstream at the provider (e.g., GitHub)
-        executor_url: str, optional
-            URL to execute the notebook document (e.g., Binder)
+        user, gist_id, gist, and files are (most) of the values returned by parse_gist
         """
         entries = []
         ipynbs = []
@@ -175,6 +174,10 @@ def tree_get(self, user, gist_id, gist, files):
             gist_id=gist_id
         ) if self.binder_base_url else None
 
+        # provider_url:
+        #     URL to the notebook document upstream at the provider (e.g., GitHub)
+        # executor_url: str, optional
+        #     URL to execute the notebook document (e.g., Binder)
         html = self.render_template(
             'treelist.html',
             entries=entries,
@@ -197,8 +200,12 @@ def file_get(self, user, gist_id, filename, gist, many_files_gist, file):
 
         yield self.deliver_notebook(user, gist_id, filename, gist, file, content)
 
+    # Only called by file_get
     @gen.coroutine
     def get_notebook_data(self, gist_id, filename, many_files_gist, file):
+        """
+        gist_id, filename, many_files_gist, file are all passed to file_get
+        """
         if (file['type'] or '').startswith('image/'):
             app_log.debug("Fetching raw image (%s) %s/%s: %s", file['type'], gist_id, filename, file['raw_url'])
             response = yield self.fetch(file['raw_url'])
@@ -220,11 +227,13 @@ def get_notebook_data(self, gist_id, filename, many_files_gist, file):
         else:
             return content
 
+    # Only called by file_get
     @gen.coroutine
     def deliver_notebook(self, user, gist_id, filename, gist, file, content):
         """
-        provider_url: str, optional
-            URL to the notebook document upstream at the provider (e.g., GitHub)
+        user, gist_id, filename, gist, file, are the same values as those 
+        passed into file_get, whereas content is returned from 
+        get_notebook_data using user, gist_id, filename, gist, and file.
         """
         # Enable a binder navbar icon if a binder base URL is configured
         executor_url = self.BINDER_PATH_TMPL.format(
@@ -234,6 +243,8 @@ def deliver_notebook(self, user, gist_id, filename, gist, file, content):
             path=quote(filename)
         ) if self.binder_base_url else None
 
+        # provider_url: str, optional
+        #     URL to the notebook document upstream at the provider (e.g., GitHub)
         yield self.finish_notebook(
             content,
             file['raw_url'],
@@ -246,7 +257,10 @@ def deliver_notebook(self, user, gist_id, filename, gist, file, content):
     @cached
     @gen.coroutine
     def get(self, user, gist_id, filename=''):
-
+        """
+        Encompasses both the case of a single file gist, handled by
+        `file_get`, as well as a many-file gist, handled by `tree_get`.
+        """
         user, gist_id, gist, files, many_files_gist = yield self.parse_gist(user, gist_id, filename)
 
         if many_files_gist and not filename:

nbviewer/providers/github/handlers.py

@@ -39,16 +39,18 @@ def _github_url():
     return os.environ.get('GITHUB_URL') if os.environ.get('GITHUB_URL', '') else "https://github.com/"
 
 class GithubClientMixin(object):
-    """
-    provider_label: str
-        Text to to apply to the navbar icon linking to the provider
-    provider_icon: str
-        CSS classname to apply to the navbar icon linking to the provider
-    executor_label: str, optional
-        Text to apply to the navbar icon linking to the execution service
-    executor_icon: str, optional
-        CSS classname to apply to the navbar icon linking to the execution service
-    """
+
+    # PROVIDER_CTX is a dictionary whose entries are passed as keyword arguments
+    # to the render_template method of the GistHandler. The following describe
+    # the information contained in each of these keyword arguments:
+    # provider_label: str
+    #     Text to to apply to the navbar icon linking to the provider
+    # provider_icon: str
+    #     CSS classname to apply to the navbar icon linking to the provider
+    # executor_label: str, optional
+    #     Text to apply to the navbar icon linking to the execution service
+    # executor_icon: str, optional
+    #     CSS classname to apply to the navbar icon linking to the execution service
     PROVIDER_CTX = {
         'provider_label': 'GitHub',
         'provider_icon': 'github',
@@ -301,14 +303,6 @@ def get_notebook_data(self, user, repo, ref, path):
 
     @gen.coroutine
     def deliver_notebook(self, user, repo, ref, path, raw_url, blob_url, tree_entry):
-        """
-        provider_url:
-            URL to the notebook document upstream at the provider (e.g., GitHub)
-        breadcrumbs: list of dict
-            Breadcrumb 'name' and 'url' to render as links at the top of the notebook page
-        executor_url: str, optional
-            URL to execute the notebook document (e.g., Binder)
-        """
         # fetch file data from the blobs API
         with self.catch_client_error():
             response = yield self.github_client.fetch(tree_entry['url'])
@@ -351,6 +345,13 @@ def deliver_notebook(self, user, repo, ref, path, raw_url, blob_url, tree_entry)
             except Exception as e:
                 app_log.error("Failed to decode notebook: %s", raw_url, exc_info=True)
                 raise web.HTTPError(400)
+            # Explanation of some kwargs passed into `finish_notebook`:
+            # provider_url:
+            #     URL to the notebook document upstream at the provider (e.g., GitHub)
+            # breadcrumbs: list of dict
+            #     Breadcrumb 'name' and 'url' to render as links at the top of the notebook page
+            # executor_url: str, optional
+            #     URL to execute the notebook document (e.g., Binder)
             yield self.finish_notebook(nbjson, raw_url,
                 provider_url=blob_url,
                 executor_url=executor_url,

nbviewer/providers/local/handlers.py

@@ -158,12 +158,6 @@ def get_notebook_data(self, path):
 
     @gen.coroutine
     def deliver_notebook(self, fullpath, path):
-        """
-        breadcrumbs: list of dict
-            Breadcrumb 'name' and 'url' to render as links at the top of the notebook page
-        title: str
-            Title to use as the HTML page title (i.e., text on the browser tab)
-        """
         try:
             with io.open(fullpath, encoding='utf-8') as f:
                 nbdata = f.read()
@@ -174,6 +168,11 @@ def deliver_notebook(self, fullpath, path):
                 raise web.HTTPError(404)
             raise ex
 
+        # Explanation of some kwargs passed into `finish_notebook`:
+        # breadcrumbs: list of dict
+        #     Breadcrumb 'name' and 'url' to render as links at the top of the notebook page
+        # title: str
+        #     Title to use as the HTML page title (i.e., text on the browser tab)
         yield self.finish_notebook(nbdata,
                                    download_url='?download',
                                    msg="file from localfile: %s" % path,