Merge branch 'master' into ghe-raw-patch

# Conflicts:
#	nbviewer/providers/github/handlers.py

Author: ivan-gomes

README.md

@@ -25,7 +25,7 @@ $ docker run -p 8080:8080 -e 'GITHUB_OAUTH_KEY=YOURKEY' \
                           jupyter/nbviewer
 ```
 
-Or to use your GitHub personal access token, you can set just `GITHUB_API_TOKEN`.
+Or to use your GitHub personal access token, you can just set `GITHUB_API_TOKEN`.
 
 
 ## GitHub Enterprise
@@ -70,7 +70,7 @@ $ docker run -p 8080:8080 nbviewer
 The Notebook Viewer uses `memcached` in production. To locally try out this
 setup, a [docker-compose](https://docs.docker.com/compose/) configuration is
 provided to easily start/stop the `nbviewer` and `memcached` containers
-together from a your current branch. You will need to install `docker` prior
+together from your current branch. You will need to install `docker` prior
 to this.
 
 #### Run
@@ -145,7 +145,7 @@ Providers are sources of notebooks and directories of notebooks and directories.
 - `local`
 
 #### Writing a new Provider
-There are several already additional providers
+There are already several providers
 [proposed/requested](https://github.com/jupyter/nbviewer/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Atag%3AProvider). Some providers are more involved than others, and some,
 such as those which would require user authentication, will take some work to
 support properly.
@@ -183,7 +183,7 @@ Formats are ways to present notebooks to the user.
 #### Writing a new Format
 If you'd like to write a new format, open a ticket, or speak up on [gitter][]!
 We have some work yet to do to support your next big thing in notebook
-publishing, and we'd love to here from you.
+publishing, and we'd love to hear from you.
 
 #### Config file
 
@@ -193,7 +193,7 @@ For example, to configure the value of a configurable `foo`, add the line `c.NBV
 
 ## Securing the Notebook Viewer
 
-You can run the viewer as a [JupyterHub 0.7+ service](https://jupyterhub.readthedocs.io/en/latest/reference/services.html). Running the viewer as a service prevents users who have not authenticated with the Hub from acccessing the nbviewer instance. This setup can be useful for protecting access to local notebooks rendered with the `--localfiles` option.
+You can run the viewer as a [JupyterHub 0.7+ service](https://jupyterhub.readthedocs.io/en/latest/reference/services.html). Running the viewer as a service prevents users who have not authenticated with the Hub from accessing the nbviewer instance. This setup can be useful for protecting access to local notebooks rendered with the `--localfiles` option.
 
 Add an entry like the following to your `jupyterhub_config.py` to have it start nbviewer as a managed service:
 

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()
@@ -214,7 +216,6 @@ def statsd(self):
         if hasattr(self, '_statsd'):
             return self._statsd
         if self.settings['statsd_host']:
-            print(self.settings)
             self._statsd = statsd.StatsClient(
                 self.settings['statsd_host'],
                 self.settings['statsd_port'],
@@ -263,13 +264,13 @@ def render_template(self, name, **namespace):
         namespace.update(self.template_namespace)
         template = self.get_template(name)
         return template.render(**namespace)
-    
+
     # 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_status_code_template(self, status_code, **namespace):
         return self.render_template('%d.html' % status_code, **namespace)
-    
+
     def render_error_template(self, **namespace):
         return self.render_template('error.html', **namespace)
 
@@ -630,6 +631,31 @@ def filter_formats(self, nb, raw):
             except Exception as err:
                 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 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 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
@@ -658,30 +684,10 @@ def finish_notebook(self, json_notebook, download_url, msg=None,
             Notebook document in JSON format
         download_url: str
             URL to download the notebook document
-        provider_url: str, optional
-            URL to the notebook document upstream at the provider (e.g., GitHub)
-        provider_icon: str, optional
-            CSS classname to apply to the navbar icon linking to the provider
-        provider_label: str, optional
-            Text to to apply to the navbar icon linking to the provider
         msg: str, optional
             Extra information to log when rendering fails
-        breadcrumbs: list of dict, optional
-            Breadcrumb 'name' and 'url' to render as links at the top of the notebook page
         public: bool, optional
             True if the notebook is public and its access indexed, False if not
-        format: str, optional
-            Rendering format (e.g., script, slides, html)
-        request: tornado.httputil.HTTPServerRequest, optional
-            HTTP request that triggered notebook rendering
-        title: str, optional
-            Title to use as the HTML page title (i.e., text on the browser tab)
-        executor_url: str, optional
-            URL to execute the notebook document (e.g., Binder)
-        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
         """
 
         if msg is None: