Merge pull request #24 from jbweston/ipywidgets

add support for rendering ipywidgets

Author: akhmerov

jupyter_sphinx/execute.py

@@ -3,6 +3,7 @@
 import os
 from itertools import groupby, count
 from operator import itemgetter
+import json
 
 from sphinx.util import logging
 from sphinx.transforms import SphinxTransform
@@ -23,11 +24,34 @@
 
 import nbformat
 
+from ipywidgets import Widget
+import ipywidgets.embed
 
 from ._version import __version__
 
+
 logger = logging.getLogger(__name__)
 
+WIDGET_VIEW_MIMETYPE = 'application/vnd.jupyter.widget-view+json'
+WIDGET_STATE_MIMETYPE = 'application/vnd.jupyter.widget-state+json'
+REQUIRE_URL_DEFAULT = 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js'
+
+
+def builder_inited(app):
+    """
+    2 cases
+    case 1: ipywidgets 7, with require
+    case 2: ipywidgets 7, no require
+    """
+    require_url = app.config.jupyter_sphinx_require_url
+    if require_url:
+        app.add_js_file(require_url)
+        embed_url = app.config.jupyter_sphinx_embed_url or ipywidgets.embed.DEFAULT_EMBED_REQUIREJS_URL
+    else:
+        embed_url = app.config.jupyter_sphinx_embed_url or ipywidgets.embed.DEFAULT_EMBED_SCRIPT_URL
+    if embed_url:
+        app.add_js_file(embed_url)
+
 
 ### Directives and their associated doctree nodes
 
@@ -167,6 +191,47 @@ class JupyterCellNode(docutils.nodes.container):
     """
 
 
+class JupyterWidgetViewNode(docutils.nodes.Element):
+    """Inserted into doctree whenever a Jupyter cell produces a widget as output.
+
+    Contains a unique ID for this widget; enough information for the widget
+    embedding javascript to render it, given the widget state. For non-HTML
+    outputs this doctree node is rendered generically.
+    """
+
+    def __init__(self, view_spec):
+        super().__init__('', view_spec=view_spec)
+
+    def html(self):
+        return ipywidgets.embed.widget_view_template.format(
+            view_spec=json.dumps(self['view_spec']))
+
+    def text(self):
+        return '[ widget ]'
+
+
+class JupyterWidgetStateNode(docutils.nodes.Element):
+    """Appended to doctree if any Jupyter cell produced a widget as output.
+
+    Contains the state needed to render a collection of Jupyter widgets.
+
+    Per doctree there is 1 JupyterWidgetStateNode per kernel that produced
+    Jupyter widgets when running. This is fine as (presently) the
+    'html-manager' Javascript library, which embeds widgets, loads the state
+    from all script tags on the page of the correct mimetype.
+    """
+
+    def __init__(self, state):
+        super().__init__('', state=state)
+
+    def html(self):
+        # TODO: render into a separate file if 'html-manager' starts fully
+        #       parsing script tags, and not just grabbing their innerHTML
+        # https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/html-manager/src/libembed.ts#L36
+        return ipywidgets.embed.snippet_template.format(
+            load='', widget_views='', json_data=json.dumps(self['state']))
+
+
 ### Doctree transformations
 
 class ExecuteJupyterCells(SphinxTransform):
@@ -246,6 +311,9 @@ def apply(self):
                 )
                 attach_outputs(output_nodes, node)
 
+            if contains_widgets(notebook):
+                doctree.append(JupyterWidgetStateNode(get_widgets(notebook)))
+
 
 ### Roles
 
@@ -364,6 +432,8 @@ def cell_output_to_nodes(cell, data_priority, dir):
                     text=data,
                     rawsource=data,
                 ))
+            elif mime_type == WIDGET_VIEW_MIMETYPE:
+                to_add.append(JupyterWidgetViewNode(data))
 
     return to_add
 
@@ -398,6 +468,27 @@ def execute_cells(kernel_name, cells, execute_kwargs):
     return notebook
 
 
+def get_widgets(notebook):
+    try:
+        return notebook.metadata.widgets[WIDGET_STATE_MIMETYPE]
+    except AttributeError:
+        # Don't catch KeyError, as it's a bug if 'widgets' does
+        # not contain 'WIDGET_STATE_MIMETYPE'
+        return None
+
+
+def contains_widgets(notebook):
+    widgets = get_widgets(notebook)
+    return widgets and widgets['state']
+
+
+def language_info(executor):
+    # Can only run this function inside 'setup_preprocessor'
+    assert hasattr(executor, 'kc')
+    info_msg = executor._wait_for_reply(executor.kc.kernel_info())
+    return info_msg['content']['language_info']
+
+
 def write_notebook_output(notebook, output_dir, notebook_name):
     """Extract output from notebook cells and write to files in output_dir.
 
@@ -455,7 +546,7 @@ def setup(app):
     # Configuration
     app.add_config_value(
         'jupyter_execute_kwargs',
-        dict(timeout=-1, allow_errors=True),
+        dict(timeout=-1, allow_errors=True, store_widget_state=True),
         'env'
     )
     app.add_config_value(
@@ -466,6 +557,7 @@ def setup(app):
     app.add_config_value(
         'jupyter_execute_data_priority',
         [
+            WIDGET_VIEW_MIMETYPE,
             'text/html',
             'image/svg+xml',
             'image/png',
@@ -476,6 +568,10 @@ def setup(app):
         'env',
     )
 
+    # ipywidgets config
+    app.add_config_value('jupyter_sphinx_require_url', REQUIRE_URL_DEFAULT, 'html')
+    app.add_config_value('jupyter_sphinx_embed_url', None, 'html')
+
     # JupyterKernelNode is just a doctree marker for the
     # ExecuteJupyterCells transform, so we don't actually render it.
     def skip(self, node):
@@ -507,6 +603,35 @@ def skip(self, node):
         man=render_container,
     )
 
+    # JupyterWidgetViewNode holds widget view JSON,
+    # but is only rendered properly in HTML documents.
+    def visit_widget_html(self, node):
+        self.body.append(node.html())
+        raise docutils.nodes.SkipNode
+
+    def visit_widget_text(self, node):
+        self.body.append(node.text())
+        raise docutils.nodes.SkipNode
+
+    app.add_node(
+        JupyterWidgetViewNode,
+        html=(visit_widget_html, None),
+        latex=(visit_widget_text, None),
+        textinfo=(visit_widget_text, None),
+        text=(visit_widget_text, None),
+        man=(visit_widget_text, None),
+    )
+    # JupyterWidgetStateNode holds the widget state JSON,
+    # but is only rendered in HTML documents.
+    app.add_node(
+        JupyterWidgetStateNode,
+        html=(visit_widget_html, None),
+        latex=(skip, None),
+        textinfo=(skip, None),
+        text=(skip, None),
+        man=(skip, None),
+    )
+
     app.add_directive('jupyter-execute', JupyterCell)
     app.add_directive('jupyter-kernel', JupyterKernel)
     app.add_role('jupyter-download:notebook', jupyter_download_role)
@@ -517,6 +642,8 @@ def skip(self, node):
     app.add_lexer('ipythontb', IPythonTracebackLexer())
     app.add_lexer('ipython', IPython3Lexer())
 
+    app.connect('builder-inited', builder_inited)
+
     return {
         'version': __version__,
         'parallel_read_safe': True,

setup.py

@@ -18,9 +18,9 @@
     packages = ['jupyter_sphinx'],
     install_requires = [
         'Sphinx>=0.6',
-        'ipywidgets>=6.0.0',
+        'ipywidgets>=7.0.0',
         'IPython',
-        'nbconvert>=5.4',
+        'nbconvert>=5.5',
         'nbformat',
     ],
 )

tests/test_execute.py

@@ -9,7 +9,12 @@
 
 import pytest
 
-from jupyter_sphinx.execute import JupyterCellNode, JupyterKernelNode
+from jupyter_sphinx.execute import (
+    JupyterCellNode,
+    JupyterKernelNode,
+    JupyterWidgetViewNode,
+    JupyterWidgetStateNode,
+)
 
 @pytest.fixture()
 def doctree():
@@ -160,3 +165,15 @@ def test_raises(doctree):
     tree = doctree(source)
     cell, = tree.traverse(JupyterCellNode)
     'ValueError' in cell.children[1].rawsource
+
+
+def test_widgets(doctree):
+    source = '''
+    .. jupyter-execute::
+
+        import ipywidgets
+        ipywidgets.Button()
+    '''
+    tree = doctree(source)
+    assert len(list(tree.traverse(JupyterWidgetViewNode))) == 1
+    assert len(list(tree.traverse(JupyterWidgetStateNode))) == 1