用于交互的启动按钮

您可以自动添加按钮，让用户与您的书籍内容进行互动。这可以通过引导他们访问在云端运行的 BinderHub 或 JupyterHub，或者通过使用 Thebe 使您的页面具有互动性来实现。

要使用 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}",
    ...
}

Paired ipynb files

If you're using Jupytext to pair an ipynb file with your text files, and that ipynb file is in the same folder as your content, then Binder/JupyterHub links will point to the ipynb file instead of the text file.

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",
    },
    ...
}