入门指南

使用 Jupyter Notebook 构建精良的软件

nbdev 是一个由 notebook 驱动的开发平台。只需使用轻量级标记编写 notebook，即可免费获得高质量的文档、测试、持续集成和打包！

与传统编程环境相比，nbdev 让调试和重构代码变得更加容易，因为您始终可以轻松访问实时对象。nbdev 还推广软件工程最佳实践，因为它将测试和文档放在首位。

安装

nbdev 可以在 macOS、Linux 和大多数类 Unix 操作系统上运行。它可以在 Windows 的 WSL 下运行，但不能在 cmd 或 Powershell 下运行。

您可以使用 pip 安装 nbdev

pip install nbdev

… 或使用 conda (或 mamba)

conda install -c fastai nbdev

请注意，nbdev 必须安装到您用于 Jupyter 和您的项目的同一个 Python 环境中。

如何使用 nbdev

学习如何使用 nbdev 的最佳方式是完成书面演示或视频演示

另外，还有一个视频演示的精简版，使用 unsilence Python 库加速了编码部分——它快了 27 分钟，但可能稍微难跟上。

您也可以在终端运行 nbdev_help 查看所有可用命令的完整列表

!nbdev_help
nbdev_bump_version        Increment version in settings.ini by one
nbdev_changelog           Create a CHANGELOG.md file from closed and labeled GitHub issues
nbdev_clean               Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
nbdev_create_config       Create a config file.
nbdev_docs                Create Quarto docs and README.md
nbdev_export              Export notebooks in `path` to Python modules
nbdev_filter              A notebook filter for Quarto
nbdev_fix                 Create working notebook from conflicted notebook `nbname`
nbdev_help                Show help for all console scripts
nbdev_install             Install Quarto and the current library
nbdev_install_hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
nbdev_install_quarto      Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_merge               Git merge driver for notebooks
nbdev_migrate             Convert all markdown and notebook files in `path` from v1 to v2
nbdev_new                 Create an nbdev project.
nbdev_prepare             Export, test, and clean notebooks, and render README if needed
nbdev_preview             Preview docs locally
nbdev_proc_nbs            Process notebooks in `path` for docs rendering
nbdev_pypi                Create and upload Python package to PyPI
nbdev_readme              Create README.md from readme_nb (index.ipynb by default)
nbdev_release_both        Release both conda and PyPI packages
nbdev_release_gh          Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
nbdev_release_git         Tag and create a release in GitHub for the current version
nbdev_requirements        Writes a `requirements.txt` file to `directory` based on settings.ini.
nbdev_sidebar             Create sidebar.yml
nbdev_test                Test in parallel notebooks matching `path`, passing along `flags`
nbdev_trust               Trust notebooks matching `fname`
nbdev_update              Propagate change in modules matching `fname` to notebooks that created them
nbdev_update_license      Allows you to update the license of your project.

常见问题

问：警告“Found a cell containing mix of imports and computations. Please use separate cells”（发现包含导入和计算混合的单元格。请使用单独的单元格）是什么意思？

答：您不应该拥有未导出的单元格，并且这些单元格包含 import 语句和其他代码的混合。例如，不要在单个单元格中这样做

import some_module
some_module.something()

相反，将其分成两个单元格，一个用于 import some_module，另一个用于 some_module.something()。

这样做的原因是，当创建您的文档网站时，我们通过运行 notebook 中的导入、导出的单元格和 show_doc 函数来确保您文档中所有函数的签名都是最新的。当您将导入与其他代码混合时，这些其他代码也会运行，这在创建网站时可能会导致错误（或至少减慢速度）。

问：为什么 nbdev 要求 root 访问权限？如何在没有 root 访问权限的情况下安装 Quarto？

答：当您设置第一个项目时，nbdev 会尝试自动为您下载并安装 Quarto。这是我们用来创建您的文档网站的程序。

Quarto 的标准安装过程需要 root 权限，因此 nbdev 在安装期间会要求您提供 root 密码。对于大多数人来说，这都能正常工作，一切都会自动处理——如果是这样，您可以跳过本节的其余部分，这部分讨论了如何在没有 root 权限的情况下安装。

如果您需要在 Linux 上在没有 root 权限的情况下安装 Quarto，首先 cd 到您想要存储它的位置，然后下载 Quarto，并输入

dpkg -x quarto*.deb .
mv opt/quarto ./
rmdir opt
mkdir -p ~/.local/bin
ln -s "$(pwd)"/quarto/bin/quarto ~/.local/bin

要使用这个非 root 版本的 Quarto，您需要将 ~/.local/bin 添加到您的 PATH 环境变量中。（或者，更改 ln -s 步骤将符号链接放置在您的路径中的其他位置。）

问：有人告诉我不要将 notebook 用于“严肃”的软件开发！

答：观看此视频。别担心，尽管我们在过去三年中使用 nbdev 开发了各种“非常严肃”的软件项目，包括深度学习库、API 客户端、Python 语言扩展、终端用户界面等等，我们仍然会听到这种说法！

贡献

如果您想为 nbdev 贡献代码，请务必查阅贡献指南。本项目遵守 fastai 的行为准则。参与本项目意味着您期望遵守此准则。总的来说，我们努力遵循开源软件开发中普遍接受的最佳实践。

通过在克隆的仓库中运行 nbdev_install_hooks 来确保安装了 nbdev 的 git 钩子。