nbdev1 迁移

如何更改 nbdev1 仓库以使用 nbdev2

nbdev v2 是 nbdev 的全新重写版本，不向后兼容。本页介绍您需要进行的更改，以便将 nbdev v1 仓库升级到新版本。此处显示的步骤应适用于 macOS 或 Linux（包括 Windows WSL）

最大的变化是 nbdev2 使用 Quarto 生成您的网站，而 nbdev1 使用 nbconvert 和 jekyll。您可以在 nbdev 中直接使用 Quarto 的所有功能，因此请查看 Quarto 网站，了解它支持的所有惊人功能。

初始设置

如果您在 requirements.txt 或 settings.ini 中固定了 nbdev 的版本（例如 nbdev<2），请移除版本固定。（如果您不知道这意味着什么，那么您没有固定版本，可以忽略此步骤）。

通过键入以下命令安装最新版本的 nbdev

pip install -U nbdev

或

conda install -c fastai nbdev

您可能需要重启终端，以便新命令对您的 shell 可见。

升级指令

nbdev 稍微改变了像 export 和 default_exp 这样的“指令注释”的工作方式，以便与 Quarto 的处理方式保持一致。现在，不再只是在开头添加一个 # 来表示指令（例如 #export），您现在需要使用 #|（例如 #|export）。您还可以选择添加一个空格（例如 #| export）。

要自动将您的指令升级到新格式，请在您的仓库根目录运行

nbdev_migrate

您现在应该通过运行以下命令测试是否可以导出模块

nbdev_export

请注意，nbdev_export 替换了 nbdev_build_lib。运行 nbdev_export -h 查看您可以传递给它的选项（通常您不需要传递任何选项）。要查看 nbdev2 中所有可用命令的列表，请运行 nbdev_help。

添加和删除文件

首先通过运行以下命令设置一个变量，其值为您的库名称（将“yourlib”替换为您的库子目录名称）

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

cat >>.gitignore <<EOF
_docs/
_proc/
EOF

如您所见，我们已经移除了 Makefile – 这是因为之前由 make 完成的所有操作现在都由 nbdev 命令直接处理了。

注意

所有与文档相关的文件都应包含在您的 nbs_path 中，并且所有路径都应相对于它。如果您在 settings.ini 文件中设置了 nbs_path，则将您的 styles.css 文件复制到您的 nbs_path 文件夹内。

如果您使用 GitHub Actions 进行持续集成 (CI)，您也可以按如下方式更新它以使用 nbdev

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/

更新指令名称

许多指令已更改名称。我们将使用 perl 来修复它们。在您的仓库根目录运行这些行

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

这些更改将以下指令转换为使用 Quarto 内置的功能

  • hide_input –> echo: false
  • hide_output –> output: false
  • skip –> eval: false

它们还更新了 nbdev_export Python 函数的新位置和名称。

如果您有任何笔记本曾要求 nbdev1 跳过（使用 all_slow），则需要在笔记本顶部添加一个包含 YAML frontmatter 的原始单元格。Frontmatter 需要包含 skip_showdoc: true 以避免在渲染文档时运行单元格，并包含 skip_exec: true 以在运行测试时跳过此笔记本。例如，要同时执行这两项操作，您可以添加一个原始单元格（或更新现有的 frontmatter 原始单元格）以包含

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

或者您也可以在 Markdown 单元格中添加这些标志，

# title
> description

- skip_showdoc: true
- skip_exec: true

编辑工作流权限

确保您的工作流权限设置为“读写权限”，您可以在“设置”→“Actions”→“General”→“Workflow permissions”中找到此设置

GitHub Pages 设置
重要提示

未能设置正确的权限可能会导致出现如下错误消息

 fatal: unable to access 'https://github.com/user/repo.git/': The requested URL returned error: 403
  Error: Action failed with "The process '/usr/bin/git' failed with exit code 128"

编辑 GitHub Pages 权限

此时，您需要将所做的更改提交到 GitHub。等待 GitHub Actions 运行并通过。您的仓库中将自动创建一个名为 gh-pages 的新分支。您需要配置 GitHub Pages 设置，使其从此分支构建，如下所示

在“设置”→“Pages”下访问此屏幕

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

Actions 工作流权限

最后步骤

您现在应该编辑 settings.ini，并将 doc_path 从 docs 更改为 _docs，因为 nbdev2 将在那里构建您的网站。

如果您的网站使用自定义域名，则应将 CNAME 文件移动到包含您的笔记本的目录中。

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

nbdev_preview

现在准备提交到 GitHub

nbdev_prepare

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