启动交互式计算接口

因为 Jupyter Book 是用 Jupyter 笔记本构建的,所以您可以允许用户直接从您的书在云中启动实时的 Jupyter 会话。这使得读者可以在传统的编码界面中快速地与您的内容交互。他们通过点击一个将他们带到交互式环境的 Launch Button 来做到这一点。

有许多在线笔记本服务——这篇文章提供了一个很好的比较——下面的章节描述了 Jupyter Book 提供的可用集成。

通用 Launch 按钮配置

对于每个交互式服务,您都需要告诉 Jupyter Book 您的图书内容在线的位置。要做到这一点,请在 _config.yml 中配置:

# Information about where the book exists on the web
repository:
  url                       : https://github.com/yourusername/yourbookrepo  # Online location of your book
  path_to_book              : path/to/book  # Optional path to your book, relative to the repository root
  branch                    : master  # Which branch of the repository should be used when creating links (optional)

下面是对每个选项的简要描述:

url: 一个 GitHub 仓库,包括你的源文件,用于构建 Jupyter Book。这些文件可以位于存储库的根目录中,也可以位于子文件夹中(在这种情况下,您应该使用 path_to_book)。

path_to_book: 相对于存储库的根目录,到图书源文件的路径。如果你的书在存储库的子文件夹中(例如 docs/book/),可以使用这个方法。

branch: 存储图书源文件的分支(不是通常存在于 gh-pages/ 分支的图书的构建文件)。

控制打开的笔记本界面

Binder 和 JupyterHub 会话可以使用“经典的” Jupyter Notebook 或新的 JupyterLab 接口后端打开(详情见 jupyter.org)。这是用以下方式配置的:

launch_buttons:
  notebook_interface: "jupyterlab"  # or "classic"

在选择界面时需要考虑的一件事是,以 MyST Markdown 文本格式编写的笔记本不会被打开。

如果您希望将这些文件作为笔记本打开,那么首先必须确保您的图书的 Binder/JupyterHub 环境中安装了 jupytext>=0.16(在谷歌 Colab 中不支持此特性)。然后你有两个选择:

  • 使用“classic”界面,它会立即打开这些文件作为笔记本。

  • “jupyterlab”界面(在撰写本文时)还没有实现这种行为,所以你需要指导读者右键单击 Markdown 文件,然后点击“在笔记本编辑器中打开”。

添加 Binder 启动按钮

可以使用 BinderHub 构建运行存储库所需的环境,并提供一个链接,允许其他人与该存储库进行交互。如果你的 Jupyter Book 是在 GitHub 上托管的,你可以自动插入链接到运行在 BinderHub 的 Jupyter Notebook 的按钮。当用户单击该按钮时,他们将被带到页面的实时版本。如果您的代码不需要大量的 CPU 或 RAM,您可以使用在 https://mybinder.org 上运行的免费公共 BinderHub。

要自动在你的 Jupyter Book 的每一页中包含 Binder 链接按钮,请使用 _config.yml 中的以下配置:

launch_buttons:
  binderhub_url: "https://mybinder.org"  # The URL for your BinderHub (e.g., https://mybinder.org)

通过添加这个配置以及上面的存储库 url 配置,Jupyter Book 将插入 Binder 链接到从笔记本内容构建的任何页面。

添加 JupyterHub 启动按钮

JupyterHub 允许您托管一个在线服务,该服务为用户提供自己的 Jupyter 服务器和您为他们指定的环境。它允许用户访问您在云中提供的资源和硬件,并允许您对用户进行身份验证,以控制谁可以访问您的硬件。

与 Binder 链接按钮类似,您还可以自动包含交互链接,这些链接将您的读者发送到正在运行您页面的动态交互版本的 JupyterHub。这是通过使用 nbgitpuller 服务器扩展来完成的。

你可以使用以下配置设置 JupyterHub 的位置(你可以自己设置,使用指南如 zero to jupyterhub for kubernetesthe littlest jupyterhub):

launch_buttons:
  jupyterhub_url: "your-hub-url"  # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)

在你的 JupyterHub 服务器上,你需要安装两个依赖项:

  1. 要克隆带有启动链接的笔记本,服务器需要 nbgitpuller

  2. 要打开 myst-markdown 作为笔记本,服务器需要 jupytext>=0.16

你可以在 DockerFile 中添加:

RUN pip install jupytext nbgitpuller

添加 Google Colab 启动按钮

如果你的 Jupyter Book 托管在 GitHub 上,你可以自动插入按钮,链接到运行在 Google Colab 上的 Jupyter Notebook。当用户单击该按钮时,他们将被带到页面的实时版本。

类似于 Binder 链接按钮,你可以在 _config.yml 中自动包含以下配置的谷歌 Colab 链接按钮:

launch_buttons:
  colab_url: "https://colab.research.google.com"

注解

谷歌 Colab 链接只适用于具有 .ipynb 扩展名的页面。