From dea84886c4c72ba58838ebcac56eeb4540f320e2 Mon Sep 17 00:00:00 2001
From: Sylvain Corlay <sylvain.corlay@gmail.com>
Date: Tue, 12 Feb 2019 13:30:20 +0100
Subject: [PATCH] Document collect_template_paths

---
 voila/handler.py | 22 ++++++++++++++++------
 voila/paths.py   | 23 +++++++++++++++++++----
 2 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/voila/handler.py b/voila/handler.py
index 6509ff268..79f9c5928 100644
--- a/voila/handler.py
+++ b/voila/handler.py
@@ -14,13 +14,23 @@
 from nbconvert.preprocessors.execute import executenb
 from nbconvert import HTMLExporter
 
+from .paths import collect_template_paths
+
 
 class VoilaHandler(JupyterHandler):
-    def initialize(self, notebook_path=None, strip_sources=True, nbconvert_template_paths=None, config=None):
-        self.notebook_path = notebook_path
-        self.strip_sources = strip_sources
-        self.template_path = nbconvert_template_paths
-        self.exporter_config = config
+
+    def initialize(self, **kwargs):
+        self.notebook_path = kwargs.pop('notebook_path', [])    # should it be []
+        self.strip_sources = kwargs.pop('strip_sources', True)
+        self.nbconvert_template_paths = kwargs.pop('nbconvert_template_paths', [])
+        self.exporter_config = kwargs.pop('config', None)
+
+        collect_template_paths(
+            self.nbconvert_template_paths,
+            [],  # static_paths,
+            [],  # tornado templates,
+            'default'
+        )
 
     @tornado.web.authenticated
     @tornado.gen.coroutine
@@ -64,7 +74,7 @@ def get(self, path=None):
 
         exporter = HTMLExporter(
             template_file='voila.tpl',
-            template_path=self.template_path,
+            template_path=self.nbconvert_template_paths,
             config=self.exporter_config
         )
 
diff --git a/voila/paths.py b/voila/paths.py
index 8b14964c1..fc9cad5db 100644
--- a/voila/paths.py
+++ b/voila/paths.py
@@ -15,11 +15,26 @@
 
 
 def collect_template_paths(
+    """
+    Voila supports custom templates for rendering notebooks.
+
+    For a specified template name, `collect_template_paths` collects
+        - nbconvert template paths,
+        - static paths,
+        - tornado template paths,
+    by looking in the standard Jupyter data directories (PREFIX/share/jupyter/voila/template)
+    with different prefix values (user directory, sys prefix, and then system prefix) which
+    allows users to override templates locally.
+
+    The function will recursively load the base templates upon which the specified template
+    may be based.
+    """
        nbconvert_template_paths,
        static_paths,
-       template_paths,
+       tornado_template_paths,
        template_name='default'):
-    # we look at the usual jupyter locations, and for development purposes also
+
+    # We look at the usual jupyter locations, and for development purposes also
     # relative to the package directory (with highest precedence)
     template_directories = \
         [os.path.abspath(os.path.join(ROOT, '..', 'share', 'jupyter', 'voila', 'template', template_name))] +\
@@ -39,7 +54,7 @@ def collect_template_paths(
                 collect_template_paths(
                     nbconvert_template_paths,
                     static_paths,
-                    template_paths,
+                    tornado_template_paths,
                     conf.get('base_template', 'default'))
 
             extra_nbconvert_path = os.path.join(dirname, 'nbconvert_templates')
@@ -58,7 +73,7 @@ def collect_template_paths(
             # if not os.path.exists(extra_template_path):
             #    log.warning('template named %s found at path %r, but %s does not exist', template_name,
             #                dirname, extra_template_path)
-            template_paths.insert(0, extra_template_path)
+            tornado_template_paths.insert(0, extra_template_path)
 
             # We don't look at multiple directories, once a directory with a given name is found at a
             # given level of precedence (for instance user directory), we don't look further (for instance