nbdev迁移指南：从旧版本升级到最新版本的完整教程

nbdev迁移指南：从旧版本升级到最新版本的完整教程

【免费下载链接】nbdev Create delightful software with Jupyter Notebooks 项目地址: https://gitcode.com/gh_mirrors/nb/nbdev

想要将你的nbdev项目从旧版本顺利升级到最新版本？这份终极迁移指南将为你提供简单快速的步骤，让你轻松完成从nbdev1到nbdev2的转换。nbdev作为基于Jupyter Notebooks的软件开发工具，在版本2中引入了革命性的变化，特别是采用了Quarto作为文档生成引擎，让你的代码文档更加现代化和专业。

🚀 为什么需要迁移到nbdev2？

nbdev v2是一个完全重写的版本，与v1不向后兼容。最大的变化是nbdev2使用Quarto来生成你的网站，而nbdev1使用的是nbconvert和Jekyll。这意味着你可以直接使用Quarto的所有强大功能，获得更好的文档体验。

📋 迁移前的准备工作

检查版本依赖

首先检查你的项目中是否固定了nbdev版本。在requirements.txt或settings.ini中查找类似nbdev<2的版本锁定，如果有的话需要移除。

安装最新版本

运行以下命令安装最新版本的nbdev：

pip install -U nbdev

或者使用conda：

conda install -c fastai nbdev

安装完成后，可能需要重启终端才能使新命令生效。

🔄 自动升级指令格式

nbdev对"指令注释"的格式进行了调整，以与Quarto保持一致。现在不再使用简单的#export格式，而是使用#| export格式。

运行迁移命令自动升级你的指令：

nbdev_migrate

这个命令会自动将你项目中所有Notebook的指令格式从v1升级到v2。

🗂️ 文件结构调整

移除旧文件

设置你的库名变量，然后执行以下清理操作：

export LIBNAME=yourlib
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

📝 更新指令名称

多个指令的名称发生了变化。运行以下命令自动修复：

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/' {} +

这些更改将以下指令更新为使用Quarto内置功能：

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

⚙️ 配置GitHub工作流

如果你使用GitHub Actions进行持续集成，需要更新工作流配置：

rm -f .github/workflows/main.yml
curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/.github/workflows/test.yaml
curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/.github/workflows/deploy.yaml
mv deploy.yaml test.yaml .github/workflows/

设置工作流权限

确保你的工作流权限设置为"读取和写入权限"，这可以在Settings → Actions → General → Workflow permissions中找到。

🌐 配置GitHub Pages

提交更改到GitHub后，GitHub Actions会自动运行并创建一个名为gh-pages的新分支。你需要配置Pages使用这个分支：

• 在Source下拉列表中选择"从分支部署"
• 指定gh-pages作为分支
• 指定/root作为位置
• 点击保存

✅ 最终验证步骤

更新配置文件

编辑settings.ini，将doc_path从docs更改为_docs，因为这是nbdev2构建网站的位置。

本地预览

在推送到GitHub之前，通过运行以下命令检查你的网站在本地是否正常：

nbdev_preview

提交更改

准备提交到GitHub：

nbdev_prepare

现在你可以像往常一样提交到GitHub。最后，通过点击仓库中的Settings选项卡，然后点击左侧边栏中的Pages来更新GitHub Pages。设置"Source"为gh-pages分支和/root文件夹。

💡 迁移成功的关键提示

• 备份重要文件：在开始迁移前，确保备份你的项目。
• 逐步测试：在每个步骤后都进行测试，确保功能正常。
• 利用迁移工具：nbdev_migrate命令会自动处理大部分兼容性问题。

通过遵循这个完整的迁移指南，你可以顺利地将你的nbdev项目从旧版本升级到最新版本，享受Quarto带来的现代化文档体验！🎉

【免费下载链接】nbdev Create delightful software with Jupyter Notebooks 项目地址: https://gitcode.com/gh_mirrors/nb/nbdev