NeuromatchAcademy课程内容JupyterBook构建指南
什么是JupyterBook
JupyterBook是一个基于Python的工具，能够将Jupyter Notebook、Markdown文件和其他内容格式整合成一个美观、可交互的在线书籍。NeuromatchAcademy项目使用JupyterBook来组织和展示其完整的课程内容，为学习者提供统一的学习界面。
本地构建环境准备
1. 获取必要代码库
构建过程需要三个主要组件：
- 课程内容主库（包含核心教学材料）
- nmaci库（包含构建脚本和依赖项）
- precourse库（包含预备课程内容）
建议使用以下方式获取这些组件：
# 获取课程内容库（仅最新版本）
git clone 课程内容库地址 --depth=1
# 下载nmaci库
wget nmaci库下载地址
tar -xzf main.tar.gz; rm -rf main.tar.gz
# 下载precourse库
wget precourse库下载地址
tar -xzf main.tar.gz; rm -rf main.tar.gz
2. 安装依赖项
构建环境需要特定的Python包，特别注意JupyterBook的版本要求：
cd course-content
pip install -r ../nmaci-main/requirements.txt
pip install -r requirements.txt
pip install jupyter-book==0.10.2 # 必须使用此特定版本
版本注意：目前项目仅兼容JupyterBook 0.10.2版本，新版本在目录文件处理方式上有重大变更，会导致构建失败。
构建流程详解
1. 整合预备课程内容
预备课程内容需要合并到主课程结构中：
# 移动预备课程教程文件
mv ../precourse-main/tutorials/W0D* tutorials/
# 合并材料配置文件
cat ../precourse-main/tutorials/materials.yml tutorials/materials.yml > out.yml
mv out.yml tutorials/materials.yml
# 移动预备课程资源
mv ../precourse-main/prereqs/ .
2. 创建符号链接
为保持目录结构一致性，需要创建符号链接：
ln -s ../tutorials book/tutorials
ln -s ../projects book/projects
ln -s ../prereqs book/prereqs
3. 生成书籍配置文件
使用nmaci中的脚本生成书籍目录结构：
python ../nmaci-main/scripts/generate_book.py [student|instructor]
参数说明：
student：生成学生版书籍instructor：生成教师版书籍
重要提示：此脚本生成的临时文件不应提交到代码库中。
4. 构建完整书籍
执行构建命令：
jupyter-book build book
构建完成后，会在book/_build目录下生成完整的HTML内容，可通过浏览器打开index.html文件预览效果。
技术原理与最佳实践
构建系统工作原理
-
目录结构生成：
generate_book.py脚本解析materials.yml文件，动态创建_toc.yml目录结构文件。 -
内容转换：JupyterBook会将Markdown和Notebook文件转换为统一的HTML格式，保持代码单元格的可交互性。
-
主题定制：项目可能使用了自定义的JupyterBook主题来保持NeuromatchAcademy的品牌一致性。
常见问题排查
-
版本冲突：如果构建失败，首先检查JupyterBook版本是否为0.10.2。
-
符号链接问题：在Windows系统上可能需要管理员权限创建符号链接，或使用其他替代方案。
-
依赖项缺失：确保所有requirements.txt中的包都已正确安装。
进阶使用建议
对于希望深度定制课程内容的开发者：
-
自定义主题：可以修改
book/_config.yml文件调整书籍外观。 -
内容过滤：通过修改
generate_book.py脚本可以实现不同版本的内容筛选。 -
本地测试：构建前建议先使用
jupyter-book build --all book命令进行全面验证。
通过这套构建系统，NeuromatchAcademy能够高效地维护和更新其丰富的计算神经科学课程内容，为全球学习者提供优质的学习资源。
