启动交互式计算接口¶
因为 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 kubernetes 或 the littlest jupyterhub):
launch_buttons:
jupyterhub_url: "your-hub-url" # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)
在你的 JupyterHub 服务器上,你需要安装两个依赖项:
要克隆带有启动链接的笔记本,服务器需要
nbgitpuller
。要打开 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
扩展名的页面。