从nbdev1迁移到nbdev2的完整指南

从nbdev1迁移到nbdev2的完整指南

nbdev Create delightful software with Jupyter Notebooks 项目地址: https://gitcode.com/gh_mirrors/nb/nbdev

迁移背景与概述

nbdev2是nbdev项目的全新重写版本，带来了许多重大改进，但同时也引入了一些不兼容的变化。本文将详细介绍如何将现有的nbdev1项目迁移到nbdev2环境。

最显著的变化是nbdev2采用了Quarto作为文档生成引擎，取代了nbdev1中使用的nbconvert和Jekyll组合。Quarto提供了更强大的文档生成功能，同时也带来了更灵活的配置选项。

准备工作

环境配置

首先需要确保你的开发环境已经准备好：

1. 移除任何对nbdev版本的固定限制（如在requirements.txt或settings.ini中的nbdev<2这样的约束）
2. 安装最新版nbdev：

pip install -U nbdev

或者使用conda：

conda install -c fastai nbdev

安装完成后，建议重启终端以确保新命令可用。

指令语法升级

nbdev2对指令语法进行了调整以与Quarto保持一致：

• 旧语法：#export
• 新语法：#|export 或 #| export

自动迁移指令

运行以下命令自动更新项目中的所有指令：

nbdev_migrate

迁移完成后，测试模块导出功能：

nbdev_export

注意：nbdev_export替代了原来的nbdev_build_lib命令。可以通过nbdev_export -h查看可用选项，通常不需要额外参数。

项目结构调整

文件清理与添加

执行以下操作清理旧版本文件并添加必要的新文件：

# 设置你的库名称变量
export LIBNAME=your_library_name

# 移除不再需要的文件
git rm Makefile
git add $LIBNAME/_modidx.py
rm -rf docs
rm -f .gitconfig 
rm -f .git/hooks/post-merge
rm -f setup.py

# 添加新文件
curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/styles.css
curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/setup.py

# 更新.gitignore
cat >>.gitignore <<EOF
_docs/
_proc/
EOF

文档路径说明

所有文档相关文件现在都应放在nbs_path指定的目录中。如果settings.ini中设置了nbs_path，请确保将styles.css文件移动到此目录下。

指令名称变更

多个指令名称发生了变化，使用以下命令批量更新：

find . -name '*.ipynb' -exec perl -pi -e 's/#\\|\\s*hide_input/#| echo: false/' {} +
find . -name '*.ipynb' -exec perl -pi -e 's/#\\|\\s*hide_output/#| output: false/' {} +
find . -name '*.ipynb' -exec perl -pi -e 's/#\\|\\s*skip/#| eval: false/' {} +
find . -name '*.ipynb' -exec perl -pi -e 's/from nbdev.export import notebook2script/from nbdev import nbdev_export/' {} +
find . -name '*.ipynb' -exec perl -pi -e 's/notebook2script/nbdev_export/' {} +

主要变更包括：

• hide_input → echo: false
• hide_output → output: false
• skip → eval: false

特殊用例处理

对于使用all_slow标记的笔记本，需要添加YAML frontmatter来替代原有功能。在笔记本顶部添加一个原始单元格，内容如下：

---
skip_showdoc: true
skip_exec: true
---

或者也可以在markdown单元格中添加：

# 标题
> 描述

- skip_showdoc: true
- skip_exec: true

GitHub配置调整

工作流权限设置

确保GitHub Actions具有"读写"权限，路径为： Settings → Actions → General → Workflow permissions

页面部署设置

1. 提交所有更改并等待GitHub Actions运行完成
2. 自动创建gh-pages分支后，配置GitHub Pages：
   • 设置 → Pages
   • 源选择"从分支部署"
   • 分支选择gh-pages
   • 位置选择/root
   • 保存设置

最终迁移步骤

1. 修改settings.ini，将doc_path从docs改为_docs
2. 如果使用自定义域名，将CNAME文件移动到笔记本所在目录
3. 本地预览网站：

nbdev_preview

4. 准备提交：

nbdev_prepare

5. 提交更改到GitHub

完成以上步骤后，你的nbdev1项目就已成功迁移到nbdev2，可以享受新版本带来的各项改进和功能增强了。

nbdev Create delightful software with Jupyter Notebooks 项目地址: https://gitcode.com/gh_mirrors/nb/nbdev