在 ReadTheDocs 上使用 jupyterlite-sphinx 部署

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

JupyterLite 资产可以复制到 conf.py 中的默认静态目录，例如 docs/_static，使用 html_static_path，或者使用 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 将资产直接转储到文档文件夹中。此方法可用于部署直接启动到 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