使用 jupyterlite-sphinx 在 ReadTheDocs 上部署

Sphinx 不仅是科学 Python 文档社区，也是更广泛的 Python 生态系统以及许多其他语言的文档主力。它非常适合构建任何规模的网站，并且像 myst-nb 这样的工具使其非常适合包含可执行甚至交互式内容。

JupyterLite 资产可以复制到 conf.py 中的默认静态目录，例如使用 html_static_path 复制到 docs/_static，或者使用 html_extra_path 替换整个网站。

预览拉取请求

您可能还需要启用 Read The Docs 的自动构建拉取请求文档功能，以便在新拉取请求打开时自动获取预览链接。

复杂方式

以下是关于使用 Sphinx 构建的底层钩子和配置的更高级部分。

Sphinx 部署方法几乎可以透明地与 ReadTheDocs 配合使用，只需在存储库的根目录中添加一个 .readthedocs.yml 文件。

提示

请参阅 JupyterLite 的 .readthedocs.yml 以获取示例。

html_static_path

此搜索路径可以合并多层深度，因此您的主题资产、"金牌大师" JupyterLite 资产以及您希望进行的任何自定义都可以组合在一起。

html_static_path = [
    "_static",
    "../upstream-jupyterlite",
    "../my-jupyterlite"        # <- these "win"
]

复合目录最终将位于 docs/_build/_static 中。

提示

请参阅 JupyterLite 的 conf.py 以获取示例方法，尽管它可能比您需要的复杂得多，因为它首先需要构建自身！这种复杂性在 dodo.py 中进行管理。

html_extra_path

一个稍微激进的方法是使用 html_extra_path 将资产直接转储到 doc 文件夹中。此方法可用于部署一个直接启动到您的 JupyterLite 的网站。

调整上述示例

html_extra_path = ["../upstream-jupyterlite", "../my-jupyterlite"]

同样，最后写入的 index.html 将“胜出”并显示给访问 / 的访问者，这会立即重定向到 schema 中定义的 appUrl。

sphinx-autobuild

如果使用 Sphinx，sphinx-autobuild 提供了一种方便的方式来管理静态内容和富交互式 HTML，例如您的 JupyterLite。

sphinx-autobuild docs docs/_build

这将重新生成您的文档网站并自动刷新您打开的任何浏览器。由于您的 JupyterLite 主要由静态资产组成，因此默认情况下更改不会触发刷新。

启用 -a 标志将允许在静态资产更改时重新加载，但代价是当任何文件更改时重新构建整个网站……这可以通过 -j<N> 标志进行改进，但并非与所有 sphinx 扩展兼容。

sphinx-autobuild docs docs/_build -aj8