Jupyter + DAR/stencila = nbstencilaproxy

Jupyter + Dar 兼容性探索，用于在 Stencila 上运行 Binder

演示

点击下面的按钮，在 mybinder.org 上基于此仓库启动一个在线Jupyter实例

试试看！

通过点击“新建 > Stencila会话”打开示例Dar存档

关于

本项目是eLife Innovation Sprint 2018 和 Mozilla Global Sprint 2018（见https://github.com/mozilla/global-sprint/issues/317）的一部分

本项目包括两个模块

• 一个JavaScript包，用于在Jupyter容器中安装和运行Stencila（客户端/UI和服务）
• 一个Python包（nbstencilaproxy），用于安装和运行代理（基于nbserverproxy），以访问UI以及Stencila提供的服务；该包还扩展了Jupyter UI，添加了一个“新建Stencila会话”按钮

团队

• @minrk
• @nuest

如何？

镜像配置

在构建镜像过程中，mybinder.org会收集目录 binder/ 中的几个配置文件，并安装所需的软件和几个Stencila内核。

• environment.yml 和 requirements.txt 安装Python依赖项
• runtime.txt 添加R安装
• ìnstall.R 安装和配置R上下文以用于Stencila
• postBuild
  • 安装笔记本扩展，用于
    • 通过代理运行Stencila主机和用户界面（详细信息见下文）
    • 扩展Jupyter UI
    • 启用Stencila Jupyter上下文
  • 为Stencila安装和配置纯Python上下文

默认存档由binder/postBuild中的环境变量STENCILA_ARCHIVE设置。

在Jupyter容器中运行Stencila

我们最初使用Stencila的开发构建版本，使用node make -w -s -d /our/own/dir运行应用程序，但在配置文件存储，即dar-server时遇到了一些困难，即使用我们想要的目录，并在我们配置的完整路径上运行它，而不是由make.js相对于__dirname启动dar-server。最终，我们实现了自己的最小npm包，该包将Stencila作为依赖项拉入，并使用dist目录中的文件运行应用程序的dar-server和静态文件服务器。有关详细信息，请参阅stencila.js文件。这使我们能够控制路径，并使我们摆脱复杂的发展功能（例如substance-bundler等）。

我们还制作了自己的app.js版本，去掉了虚拟文件存储的内容（vfs），默认存储为fs（文件系统），因为这是Jupyter所需要的 - 我们不需要托管任何示例。同样，我们还构建了基于example.html的自己的index.html并提供服务，这使我们能够直接渲染DAR文档而不是示例列表和指令，并使用我们的app.js。

相关的路径配置包括本地存储路径以及客户端使用的URL，通过nbserverproxy访问dar-server。

Dockerfile安装我们的辅助npm包，并添加配置nbserverproxy工具（参见requirements.txt和jupyter_notebook_config.py）。

将Stencila连接到Jupyter内核

Stencila为R、Python、SQL、JavaScript（在浏览器中）和Node.js提供了“执行上下文”（相当于Jupyter的“内核”）。执行上下文与内核在许多方面不同，包括单元格的本地执行和依赖项分析。这两者对于Stencila文章和表格的反应式、函数式执行模型都是必要的。

我们可以在Docker镜像中安装这些执行上下文。然而，Stencila还有一个JupyterContext，它充当Stencila API和Jupyter内核之间的桥梁。因此，由于基础jupyter/minimal-notebook镜像已经安装了Python的Jupyter内核，所以我们决定使用它。然而，这意味着Stencila UI的一些反应式方面可能无法按预期工作。此外，JupyterContext尚未得到充分开发或测试。

我们在Docker镜像中包含了stencila-node Node.js包，该包提供JupyterContext以及NodeContext（用于执行JavaScript）和SqliteContext（用于执行SQL）。

通过代理提供Stencila

nbstencilaproxy提供了Jupyter服务器和笔记本扩展，以代理Stencila。它基于nbrsessionproxy，但不包括nbrsessionproxy对JupyterLab的支持。

安装

安装包

pip install git+https://github.com/minrk/nbstencilaproxy

在系统上为所有用户安装扩展

jupyter serverextension enable  --py --sys-prefix nbstencilaproxy
jupyter nbextension     install --py --sys-prefix nbstencilaproxy
jupyter nbextension     enable  --py --sys-prefix nbstencilaproxy

开发

• 使用repo2docker本地运行

# install repo2docker: https://repo2docker.readthedocs.io/en/latest/usage.html#running-repo2docker-locally

# run repo2docker for the local repository
jupyter-repo2docker --debug .

• 通过访问显示的标记URL登录，例如http://localhost:8888/?token=99a7bc13...

• 在Jupyter起始页上单击“新建 > Stencila会话”按钮，打开py-jupyter示例，或

• 通过将以下参数添加到URL中打开包含的示例

  • Python（Jupyter内核）：?archive=py-jupyter
  • R：?archive=r-markdown
  • Mini (Stencila的自身数据分析语言): ?archive=kitchen-sink

许可证

BSD 3条款许可证