在 Sphinx 文档中集成 Jupyter Notebook：nbsphinx 与 MyST-NB 完整实战指南

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Jupyter Notebook 是一种把代码、叙述文字、图片和交互组件揉合在一起的可计算叙事载体而 Sphinx 是 Read the Docs 平台背后的文档引擎。本指南以 readthedocs.org 仓库中的 官方用户指南 为骨架讲解如何通过 nbsphinx 与 MyST-NB 两大扩展把.ipynb及文本格式的 Notebook 嵌入 Sphinx 文档、渲染交互式 Widget、生成缩略图画廊并给出两者的选型建议与版本控制实践。读完本文你将能在自己的 Sphinx 项目里把 Notebook 变成正式文档页面并理解其背后的执行机制与格式差异。为什么要把 Jupyter Notebook 嵌入 Sphinx 文档Notebook 天然适合承载教程、示例和其他技术内容它同时包含代码、结果、图文与交互组件比纯静态文档更可运行。把 Notebook 嵌入 Sphinx 项目意味着这些富文档可以与普通 reStructuredText / Markdown 页面一起出现在站点导航toctree中作为 HTML 页面随整个文档站点统一构建、发布与托管借助 Read the Docs 平台获得版本化、多语言等站点级能力。在 readthedocs.org 的官方文档中这篇指南被收录于 内容指南索引并被 科学用户指南 直接引用——它是面向科学计算、交互式内容场景的推荐做法之一。引入经典.ipynbNotebook两大扩展二选一在 Sphinx 中把 Notebook 作为源文件引入主流方案有两个nbsphinx与MyST-NB。两者的意图和基础功能高度相似——都能读取.ipynb格式以及jupytext支持的附加格式配置方式也几乎一致两者差异见下文背景与选型一节。第一步创建 Notebook用你喜欢的编辑器例如 JupyterLab创建一个 Notebook比如存放在source/notebooks/Example 1.ipynb。第二步在conf.py中启用扩展二选一把扩展名加入 Sphinx 配置# conf.py —— 方案一nbsphinx extensions [ nbsphinx, ]# conf.py —— 方案二MyST-NB extensions [ myst_nb, ]第三步把 Notebook 加入toctreeNotebook 会像其他文档源文件一样被收录进站点导航。例如在根文档中加入.. toctree:: :maxdepth: 2 :caption: Contents: notebooks/Example 1{toctree} --- maxdepth: 2 caption: Contents: --- notebooks/Example 1执行 make html 之后Notebook 就会像普通 HTML 页面一样渲染在你的文档中代码单元、输出结果和图片都会被保留。 关于渲染细节的进一步定制主题、输出样式、代码高亮等需要查阅 nbsphinx 或 MyST-NB 各自的文档本文后续章节只覆盖最常见的需求。 ## 渲染交互式 Widget让文档动起来 Widget 是一类带有浏览器端表示的事件型 Python 对象可用来为 Notebook 构建交互式 GUI。基础场景使用 ipywidgets 提供滑块、文本框、按钮等控件复杂场景则可用 ipyleaflet 提供交互式地图。 这些 Widget 可以嵌入 Sphinx 生成的 HTML 文档中但有一个**关键前提必须在生成 HTML 之前保存 Widget 状态**否则渲染出来的 Widget 是空的。不同编辑器的保存方式不同 - **经典 Jupyter Notebook 界面**在 Widgets 菜单中执行 Save Notebook Widget State 操作导出 HTML 前必须手动点击一次详见 ipywidgets 官方文档的 Embedding 章节 - **JupyterLab**在 Settings 菜单中开启 Save Widget State Automatically 选项保持勾选即可自动保存 - **Visual Studio Code**据该指南记载2021 年 6 月当时还无法保存 Widget 状态因此不建议在该环境下产出含交互组件的 Notebook。 例如创建一个带 IntSlider 控件的 Notebook 并保存 Widget 状态后滑块就能在 Sphinx 构建的页面中正确渲染 [](https://link.gitcode.com/i/648345f6a2ced680720e9f33d27fe21c) 更多成熟范例可以参考ipyleaflet 在官方文档中渲染的实时交互地图以及 PyVista 面向科学 3D 可视化的多后端交互示例。 ### 两个必须注意的限制 1. **事件需要内核**Widget 本身可以嵌入静态 HTML但**事件**依赖后端内核执行。因此 interact、.observe 以及所有依赖事件的交互逻辑在纯 HTML 中不会按预期工作——静态页面只能展示控件的快照状态。 2. **额外 JS 依赖**如果 Widget 需要额外的 JavaScript 库可以在 Sphinx 应用里通过 Sphinx.add_js_file 方法注入。 ## 使用其他格式的 Notebook拥抱纯文本 经典 .ipynb 是 JSON 结构与版本控制系统协作不便。jupytext 提供了基于纯文本的 Notebook 格式其中 MyST Markdown 格式是本文示例使用的形态。一个简单的 Notebook 在 MyST Markdown 下长这样 markdown --- jupytext: text_representation: extension: .md format_name: myst format_version: 0.13 jupytext_version: 1.10.3 kernelspec: display_name: Python 3 language: python name: python3 --- # Plain-text notebook formats This is a example of a Jupyter notebook stored in MyST Markdown format. {code-cell} ipython3 import sys print(sys.version)from IPython.display import ImageImage(http://sipi.usc.edu/database/preview/misc/4.2.03.png)要让 Sphinx 识别这种 .md Notebook需要在 conf.py 中声明自定义格式通过 jupytext.reads 把 Markdown 解析回 Notebook 结构 python # conf.py —— nbsphinx 方案 nbsphinx_custom_formats { .md: [jupytext.reads, {fmt: mystnb}], } python # conf.py —— MyST-NB 方案 nb_custom_formats { .md: [jupytext.reads, {fmt: mystnb}], } 注意文本格式**不保存单元格的输出**。好消息是 Sphinx 会自动执行没有输出的 Notebook因此最终 HTML 中呈现的是补全了计算结果的完整形态。 ## 用 Notebook 创建缩略图画廊 nbsphinx 提供了从 Notebook 列表生成缩略图画廊的能力非常适合做示例集式的页面。创建画廊有两条路径 **路径一在 reStructuredText 源文件中使用 nbgallery 指令**也支持 MyST Markdown 的 {nbgallery} 形式 rst Thumbnails gallery .. nbgallery:: notebooks/Example 1 notebooks/Example 2 md # Thumbnails gallery {nbgallery} notebooks/Example 1 notebooks/Example 2 **路径二在 Notebook 中给单元格元数据打上 nbsphinx-gallery 标签**。每个编辑器修改单元格元数据的方式不同JupyterLab 中有专门的元数据编辑面板被打上标签的 Notebook 会自动进入画廊。 [](https://link.gitcode.com/i/648345f6a2ced680720e9f33d27fe21c) [](https://link.gitcode.com/i/648345f6a2ced680720e9f33d27fe21c) 真实案例方面poliastroPython 交互式天体动力学工具包在其文档中收录了多个 Notebook 示例与操作指南并用缩略图画廊统一展示它同时采用未配对的 MyST Notebook即只用文本格式、不保留 .ipynb来减小仓库体积、改善与 git 的集成。 ## 背景两种扩展的差异与选型建议 尽管 nbsphinx 与 MyST-NB 功能相似底层机制和特性覆盖仍有明显差异 | 维度 | nbsphinx | MyST-NB | | --- | --- | --- | | Markdown 转换链路 | 先经 pandoc 把 Notebook 的 Markdown 转成 reStructuredText再转 docutils AST因此假定的是 pandoc 风格 Markdown | 用 MyST-Parser 直接把 Markdown 文本转成 docutils AST使用 MyST 风格 Markdown | | 执行时机 | 在**解析阶段逐个执行**每个 Notebook | 可以**预先执行全部 Notebook**并用 jupyter-cache 缓存结果Notebook 有改动时可显著缩短构建时间 | | 缩略图画廊 | 内置 nbgallery 支持 | 目前无此功能 | | 对象粘合glue | 无 | 支持把 Notebook 中的 Python 对象嵌入文档glue 机制并提供更完善的错误报告 | | 外观细节 | 默认显示单元格编号 | 默认不显示单元格编号 | 两种 Markdown 风味大体等价但仍存在细微差异。选型建议 - 需要**其他 Notebook 格式**或**缩略图画廊**能力 → 选择 **nbsphinx** - 追求**更优化的执行工作流**、**更精简的解析机制**以及 MyST-NB 独有功能glue、更强的错误报告→ 选择 **MyST-NB**。 ## 深入Notebook 格式的三种协作模式 jupytext 面向版本控制场景给出了三条路线它们并不互斥也无需对所有 Notebook 采用同一格式 1. **使用经典 .ipynb**最直接工具链完备、无需额外软件、部件更少管理更简单。但在 git 等 VCS 中需要额外小心常见做法有三 - 提交前清空输出——能最小化冲突但计算结果是文档的一部分这一价值也随之丢失 - 使用 nbdime开源或 ReviewNB商业等工具改善 Review 流程 - 改用不依赖 Notebook 的协作工作流。 2. **用文本格式替换 .ipynb**在版本控制下表现更好也支持用普通文本编辑器甚至不支持单元格 JSON 的编辑器直接编辑。代价是文本格式不保存单元格输出。 3. **.ipynb 与文本格式配对**把文本格式文件纳入版本控制jupytext 官方推荐的 paired notebooks 方案。这是鱼与熊掌兼得的方案但少数情况下两个文件之间可能出现同步问题。 ## 仓库中的实现印证 本指南并非孤立存在readthedocs.org 仓库为它提供了完整的支撑设施 - [docs/conf.py](https://link.gitcode.com/i/92388a4b34031abe37cc152107c2cd99) 中的 intersphinx_mapping 显式注册了 nbsphinx、myst-nb、ipywidgets、ipyleaflet、poliastro、myst-parser、jupyter 等外部文档映射正是为了让上述交叉引用如 ipywidgets:embedding在构建时可解析 - [内容指南索引](https://link.gitcode.com/i/aad0e9bb5e0966d6772aec9d46180185) 将本文作为内容、主题与 SEO板块的入口之一 - [科学用户指南](https://link.gitcode.com/i/091085ffb606c71d50ef98341b647fe8) 在面向科研用户的场景中再次推荐本文并把它与 Jupyter Book、交互式数据可视化等能力并列介绍。 这也说明把 Jupyter Notebook 嵌入 Sphinx 并非小众技巧而是 Read the Docs 生态中服务教程、示例与交互式科学内容的标准姿势。结合本文的配置片段与选型建议你完全可以在自己的 Sphinx 项目里复刻这一整套流程。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐statsmodels 文档构建指南Sphinx 与 Jupyter Notebook 集成实践statsmodels 文档构建指南Sphinx 与 Jupyter Notebook 集成实践 Statsmodels 官方文档采用 Sphinx 与 Ju数据分析数据科学科研在 SciPy 文档中编写 Jupyter 教程从 .ipynb 到 MyST Markdown 的完整转换指南在 SciPy 文档中编写 Jupyter 教程从 .ipynb 到 MyST Markdown 的完整转换指南 本篇指南面向希望为 SciPy 官方文档贡献科学计算数据科学高性能计算SpeechBrain 文档系统构建指南Sphinx 文档、API 自动生成与 Jupyter 教程集成SpeechBrain 文档系统构建指南Sphinx 文档、API 自动生成与 Jupyter 教程集成 SpeechBrain 是建立在 PyTorch 之人工智能深度学习语音音频NLP预训练上一篇QQ音乐加密音频一键解密终极指南3步解锁你的音乐自由下一篇Some component创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考