0.4.x: Deprecate "classic" template for removal in 1.0.0 (voila-dashb…

…oards#1263) * Deprecate "classic" template And allow for an alternative look which is "--template lab --show-margins" * Missing capital letter in option help Co-authored-by: Duc Trung Le <[email protected]> * Missing capital letter in option help, again Co-authored-by: Duc Trung Le <[email protected]> Co-authored-by: Duc Trung Le <[email protected]>
martinRenou · Nov 29, 2022 · 05af29b · 05af29b
1 parent 14fe813
commit 05af29b
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 14 deletions.
diff --git a/docs/source/customize.rst b/docs/source/customize.rst
@@ -86,6 +86,9 @@ System administrators who want to disable changing the theme, can pass ``--Voila
 .. note::
    Changing the template from the notebook metadata may change in the future if this features moves to nbconvert.
 
+.. warning::
+   The "classic" template is being deprecated and its support will be removed in Voilà 1.0.0, an alternative is to use ``voila --template lab --show-margins`` to get a similar look.
+
 
 Creating your own template
 ==========================
@@ -247,7 +250,7 @@ Here is an example of the configuration file. This file needs to be placed in th
       """Do your stuffs here"""
       return notebook
 
-   c.Voila.prelaunch_hook = hook_function 
+   c.Voila.prelaunch_hook = hook_function
 
 - Start Voila from a python script:
 
@@ -273,7 +276,7 @@ Here is an example of a custom `prelaunch-hook` to execute a notebook with `pape
             from papermill.parameterize import parameterize_notebook
 
             # setup for papermill
-            # 
+            #
             # these two blocks are done
             # to avoid triggering errors
             # in papermill's notebook
@@ -423,7 +426,7 @@ For more information about these options, check out the `Jupyter Server <https:/
 Preheated kernels
 ==================
 
-Since Voilà needs to start a new jupyter kernel and execute the requested notebook in this kernel for every connection, this would lead to a long waiting time before the widgets can be displayed in the browser. 
+Since Voilà needs to start a new jupyter kernel and execute the requested notebook in this kernel for every connection, this would lead to a long waiting time before the widgets can be displayed in the browser.
 To reduce this waiting time, especially for heavy notebooks, users can activate the preheating kernel option of Voilà.
 
 .. warning::
@@ -451,25 +454,25 @@ will set the variable "FOO" in all preheated kernels.
 
 If the pool size does not match the user's requirements, or some notebooks need to use specific environment variables..., additional settings are needed.  The easiest way to change these settings is to provide a file named `voila.json` in the same folder containing the notebooks. Settings for preheating kernel ( list of notebooks does not need preheated kernels, number of kernels in pool, refilling delay, environment variables for starting kernel...) can be set under the `VoilaKernelManager` class name.
 
-Here is an example of settings with explanations for preheating kernel option. 
+Here is an example of settings with explanations for preheating kernel option.
 
 .. code-block:: python
 
    # voila.json
    {
       "VoilaConfiguration": {
          # Activate or deactivate preheat kernel option.
-         "preheat_kernel": true 
+         "preheat_kernel": true
       },
       "VoilaKernelManager": {
          # A list of notebook name or regex patterns to exclude notebooks from using preheat kernel.
          "preheat_blacklist": [
             "notebook-does-not-need-preheat.ipynb",
             "^.*foo.*$",
             ...
-         ], 
+         ],
          # Configuration for kernel pools
-         "kernel_pools_config": { 
+         "kernel_pools_config": {
             # Setting for `voila.ipynb` notebook
             "voila.ipynb": {
                "pool_size": 3, # Size of pool
@@ -515,7 +518,7 @@ In normal mode, Voilà users can get the `query string` at run time through the
 .. code-block:: python
 
    import os
-   query_string = os.getenv('QUERY_STRING') 
+   query_string = os.getenv('QUERY_STRING')
 
 In preheating kernel mode, users can prepend with ``wait_for_request`` from ``voila.utils``
 
@@ -536,9 +539,9 @@ If the Voilà websocket handler is not started with the default protocol (`ws`),
    {
       ...
       "VoilaKernelManager": {
-         "kernel_pools_config": { 
+         "kernel_pools_config": {
             "foo.ipynb": {
-               "kernel_env_variables": { 
+               "kernel_env_variables": {
                   "VOILA_APP_IP": "192.168.1.1",
                   "VOILA_APP_PORT": "6789",
                   "VOILA_WS_PROTOCOL": "wss"
@@ -561,7 +564,7 @@ Hiding output and code cells based on cell tags
 Voilà uses `nbconvert <https://github.com/jupyter/nbconvert>`_ under the hood to render the notebooks so we can benefit from some of its advanced functionalities to hide code and output cells based on cell tags.
 
 To hide the cell output for every cell in your notebook that has been tagged (`how to tag <https://jupyter-notebook.readthedocs.io/en/stable/changelog.html#cell-tags>`_) with "hide" in Voilà::
-    
+
     voila --TagRemovePreprocessor.remove_all_outputs_tags='{"hide"}' your_notebook.ipynb
 
 To hide both the code cell and the output cell (if any) for every cell that has been tagged with "hide"::

diff --git a/share/jupyter/voila/templates/lab/index.html.j2 b/share/jupyter/voila/templates/lab/index.html.j2
@@ -20,6 +20,25 @@
       display: none;
     }
   </style>
+{% if resources.show_margins %}
+  <style>
+    body {
+      background: var(--jp-layout-color1);
+    }
+
+    #rendered_cells {
+      padding-left: calc(calc(100% - 1200px) * 0.5);
+      padding-right: calc( calc( 100% - 1200px - 20px ) * 0.5 );
+    }
+
+    #rendered_cells > div {
+      background: var(--jp-layout-color0);
+      padding: 6ex 12ex 8ex 12ex;
+      border-radius: var(--jp-border-radius);
+      box-shadow: var(--jp-elevation-z4);
+    }
+  </style>
+{% endif %}
 {%- endblock html_head_css -%}
 
 {# this overrides the default behaviour of rendering static widgets #}
@@ -35,6 +54,7 @@
 {{ spinner.html() }}
 {{ voila_setup_helper_functions() }}
 <div id="rendered_cells" style="display: none">
+  <div>
 {%- endblock body_header -%}
 
 {%- block body_loop -%}
@@ -72,6 +92,7 @@
 {%- endblock body_loop -%}
 
 {%- block body_footer -%}
+  </div>
 </div>
 <script type="text/javascript">
   (function() {

diff --git a/voila/app.py b/voila/app.py
@@ -83,7 +83,13 @@ class Voila(Application):
             },
             _("Set the log level to logging.DEBUG, and show exception tracebacks in output.")
         ),
-        'no-browser': ({'Voila': {'open_browser': False}}, _('Don\'t open the notebook in a browser after startup.'))
+        'no-browser': ({'Voila': {'open_browser': False}}, _('Don\'t open the notebook in a browser after startup.')),
+        'show-margins': (
+            {
+                'VoilaConfiguration': {'show_margins': True},
+            },
+            _('Show left and right margins for the "lab" template, this gives a "classic" template look')
+        )
     }
 
     description = Unicode(

diff --git a/voila/configuration.py b/voila/configuration.py
@@ -37,6 +37,13 @@ class VoilaConfiguration(traitlets.config.Configurable):
         """
     )
     theme = Unicode('light', config=True)
+    show_margins = Bool(
+        False,
+        config=True,
+        help=(
+            'Show left and right margins for the "lab" template, this gives a "classic" template look'
+        )
+    )
     strip_sources = Bool(True, config=True, help='Strip sources from rendered html')
 
     file_whitelist = List(

diff --git a/voila/exporter.py b/voila/exporter.py
@@ -46,15 +46,31 @@ class VoilaExporter(HTMLExporter):
     """Custom HTMLExporter that inlines the images using VoilaMarkdownRenderer"""
 
     base_url = traitlets.Unicode(help="Base url for resources").tag(config=True)
+
     markdown_renderer_class = traitlets.Type(VoilaMarkdownRenderer).tag(config=True)
+
     # Can be a ContentsManager from notebook or jupyter_server, so Any will have to do for now
     contents_manager = traitlets.Any()
 
-    # The voila exporter overrides the markdown renderer from the HTMLExporter
-    # to inline images.
+    show_margins = traitlets.Bool(
+        True,
+        help='show left and right margins for the "lab" template, this gives a "classic" template look'
+    ).tag(config=True)
+
+    @traitlets.validate("template_name")
+    def _validate_template_name(self, template_name):
+        if template_name.value == "classic":
+            self.log.warning(
+                "\"classic\" template support will be removed in Voila 1.0.0, "
+                "please use the \"lab\" template instead with the \"--show-margins\" "
+                "option for a similar look"
+            )
+        return template_name.value
 
     @pass_context
     def markdown2html(self, context, source):
+        # The voila exporter overrides the markdown renderer from the HTMLExporter
+        # to inline images.
         cell = context['cell']
         attachments = cell.get('attachments', {})
         cls = self.markdown_renderer_class
@@ -138,4 +154,6 @@ def _init_resources(self, resources):
 
         resources.update(include_assets_functions)
 
+        resources["show_margins"] = self.show_margins
+
         return resources
diff --git a/voila/notebook_renderer.py b/voila/notebook_renderer.py
@@ -137,6 +137,7 @@ async def initialize(self, **kwargs) -> None:
             theme=self.theme,  # we now have the theme in two places
             base_url=self.base_url,
             page_config=self.page_config,
+            show_margins=self.voila_configuration.show_margins,
         )
 
         if self.voila_configuration.strip_sources: