NeuroAI_Course项目JupyterBook构建指南

什么是JupyterBook

JupyterBook是一个基于Python的工具，它允许用户将Jupyter笔记本、Markdown文件和其他内容格式组合成精美的在线书籍。NeuroAI_Course项目采用JupyterBook来整合所有课程材料，为学习者提供一个统一的交互式学习界面。

本地构建环境准备

1. 获取课程资源

构建过程需要三个核心资源库：

• 课程内容主库：包含所有教程和项目材料
• nmaci库：提供必要的脚本和依赖项
• 预课程库：包含预备周(W0D)的学习材料

2. 安装依赖项

构建环境需要以下Python包：

• jupyter-book==0.10.2（特别注意版本要求）
• 课程特定的其他依赖项

版本限制是因为新版JupyterBook对目录文件的处理方式有重大变更，可能导致构建失败。

详细构建步骤

文件准备阶段

1. 整合预课程材料：将预课程库中的W0D系列教程移动到主教程目录
2. 合并材料配置文件：将预课程和主课程的材料描述文件合并
3. 创建符号链接：在book目录下建立指向教程、项目和预备材料的链接

生成书籍配置

使用nmaci库提供的脚本生成书籍目录结构：

python generate_book.py [student|instructor]

这个脚本会：

• 根据materials.yml生成_toc.yml（书籍目录结构）
• 创建必要的Markdown文件
• 对教程笔记本进行特定修改（仅用于书籍构建）

注意：脚本生成的文件不应提交到版本控制。

构建书籍

执行构建命令：

jupyter-book build book

构建完成后，可以在book/_build目录中找到生成的HTML文件，用浏览器打开index.html即可预览。

技术细节解析

为什么需要符号链接

符号链接的使用使得：

• 保持原始文件结构的完整性
• 避免文件重复存储
• 方便书籍构建系统访问所需资源

材料合并的重要性

合并预课程和主课程材料确保了：

• 学习路径的连续性
• 统一的目录结构
• 完整的课程体验

常见问题解决方案

1. 构建失败：首先检查jupyter-book版本是否为0.10.2
2. 目录缺失：确认符号链接是否正确创建
3. 内容不完整：检查materials.yml合并是否正确

最佳实践建议

1. 使用虚拟环境隔离依赖项
2. 构建前清理之前的构建结果
3. 定期更新依赖项（但注意版本限制）

通过本指南，开发者可以顺利地在本地构建NeuroAI_Course的JupyterBook版本，便于内容开发和测试。这种构建方式不仅保证了线上线下的内容一致性，也为课程材料的迭代提供了便利。