用于交互的启动按钮

用于交互的启动按钮#

您可以自动添加按钮，使用户能够与您的书籍内容进行交互。这可以通过将他们引导至 JupyterLite 安装（在用户浏览器中运行）或 BinderHub 或 JupyterHub（在云端运行）中的任意一个，或者通过使用 Thebe 使您的页面具有交互性来实现。

要使用 JupyterLite、Binder 或 JupyterHub 链接，您首先需要配置文档仓库的 URL：

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

JupyterLite#

如果您要在页面中添加JupyterLite链接，首先确定您的JupyterLite实例将从何处提供服务，然后将该URL添加到您的配置中。在下面的示例中，我们在主页站点的基础URL和子目录interact/lab中设置了JupyterLite页面：

html_theme_options = {
    ...
    "launch_buttons": {
        "jupyterlite_url": "interact/lab/index.html"
    },
    ...
}

请访问 https://odsti.github.io/cfd-textbook 查看使用此配置提供JupyterLite服务的JupyterBook项目示例，并访问 odsti/cfd-textbook 查看驱动仓库。

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#

要在您的页面添加Google Colab链接，请添加以下配置：

html_theme_options = {
    ...
    "launch_buttons": {
        "colab_url": "https://colab.research.google.com"
    },
    ...
}

Deepnote#

要在您的页面中添加 Deepnote 链接，请添加以下配置：

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

警告

“每次点击启动按钮时，这将创建新的 Deepnote 项目。”

使用 Thebe 活代码单元格#

Thebe 将您的静态代码块转换为交互式代码块，这些代码块由 Jupyter 内核驱动。它通过在后台请求 BinderHub 内核，并将您的所有代码单元转换为交互式代码单元来实现这一点。这使得用户可以在不离开页面的情况下运行您页面上的代码。

您可以使用 Sphinx 扩展 sphinx-thebe 为您的文档添加实时代码功能。您可以通过 pip 安装 sphinx-thebe，然后通过将其添加到 conf.py 的扩展列表中来激活它：

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

如果您希望在 sphinx-book-theme 中激活 sphinx-thebe 的用户界面元素，请添加以下主题配置：

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

这将添加自定义启动按钮，并为 Thebe 添加一些用户界面元素。

如果您在主题配置中同时指定了 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",
    },
    ...
}