用于交互的启动按钮#

你可以自动添加按钮，让用户与你的书的内容互动。这要么是通过引导他们到在云端运行的 BinderHub 或 JupyterHub，要么是通过使用 Thebe 使你的页面互动。

要使用 Binder 或 JupyterHub 的链接，你首先需要配置你的文档库的网址：

html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    "repository_branch": "{your-branch}",
    "path_to_docs": "{path-relative-to-site-root},
    ...
}

Binder / BinderHub#

要添加 Binder 链接你的页面，添加以下配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "binderhub_url": "https://{your-binderhub-url}"
    },
    ...
}

JupyterHub#

要在你的页面上添加 JupyterHub 链接，请添加以下配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "jupyterhub_url": "https://{your-binderhub-url}"
    },
    ...
}

Google Colab#

要在你的页面上添加谷歌 Colab 链接，请添加以下配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "colab_url": "https://{your-colab-url}"
    },
    ...
}

Deepnote#

To add Deepnote links to your page, add the following configuration:

html_theme_options = {
    ...
    "launch_buttons": {
        "deepnote_url": "https://deepnote.com"
    },
    ...
}

警告

This will create a new Deepnote project every time you click the launch button.

Thebe 实时代码单元格#

Thebe 将你的静态代码块转换为由 Jupyter 内核驱动的 交互式 代码块。它通过要求一个 BinderHub 内核来做到这一点，*在 hood 下，将你所有的代码单元转换为 交互式 代码单元。这使得用户可以在不离开页面的情况下运行你页面上的代码

你可以使用 Sphinx 插件 sphinx-thebe 来为你的文档添加实时代码功能。你可以从 pip 安装 sphinx-thebe，然后把它放在你的 conf.py 插件列表中激活它：

extensions = [
    ...
    "sphinx_thebe"
    ...
]

如果你想在 sphinx-book-theme 中激活 sphinx-thebe 的 UI 元素，请添加以下主题配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "thebe": True,
    },
    ...
}

这将增加一个自定义的启动按钮，并为 Thebe 增加一些 UI 元素。

如果你在主题配置中还指定了一个 repository_url'，sphinx-thebe` 将使用这个仓库作为其环境：

html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    ...
}

小技巧

你也可以用 thebe_config 字典手动定制 Thebe。这将覆盖任何从你的html_theme_options配置中提取的配置。关于你可以配置的内容，请看 sphinx-thebe 文档。

配置你的源文件的相对路径#

要配置你的文档的相对路径，请添加以下配置：

html_theme_options = {
    ...
    "path_to_docs" = "{path-relative-to-repo-root}"
    ...
}

控制被打开的用户界面#

你可以控制有人点击启动按钮时打开的界面。要做到这一点，请添加以下配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "notebook_interface": "jupyterlab",
    },
    ...
}