开始使用

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

与传统的编程环境相比，nbdev使调试和重构代码变得更加容易，因为你始终可以随时使用实时对象。nbdev还提倡软件工程最佳实践，因为测试和文档都是一等公民。

• 文档使用Quarto自动生成，并托管在GitHub Pages上。文档支持LaTeX，可搜索，并自动添加超链接（包括通过nbdev-index对许多包的开箱即用支持）
• 将包发布到PyPI和conda，以及简化包发布的工具。自动遵循Python最佳实践，例如，只有导出的对象才会包含在__all__中
• 笔记本和纯文本源代码之间的双向同步，允许你使用IDE进行代码导航或快速编辑
• 测试作为普通笔记本单元编写，可以用一个命令并行运行
• 持续集成开箱即用，使用GitHub Actions运行测试并重建文档
• Git友好的笔记本，使用Jupyter/Git钩子清理不需要的元数据，并以人类可读的格式呈现合并冲突
• ……还有更多！

安装

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的最佳方式是完成书面教程或观看视频教程：

<a href="http://www.youtube.com/watch?v=l7zS8Ld4_iA" target="_blank" title="nbdev walkthrough"><img src="https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png" style="border-radius: 10px" width="560" height="315" /></a>

另外，还有一个视频教程的缩短版本，使用unsilence Python库加速了编码部分 - 它比原版快27分钟，但稍难跟上。

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

!nbdev_help

（此处省略命令列表，与原文相同）

常见问题

问：警告"Found a cell containing mix of imports and computations. Please use separate cells"是什么意思？

A: 你不应该有未导出且同时包含import语句和其他代码的单元格。例如，不要在一个单元格中这样做：

import some_module
some_module.something()

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

这样做的原因是，当我们创建你的文档网站时，我们会运行导入、导出的单元格和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步骤，将符号链接放在你的PATH中的其他位置。）

问：有人告诉我不要使用笔记本进行"严肃"的软件开发！

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

贡献

如果你想为nbdev做出贡献，请务必查看贡献指南。这个项目遵循fastai的行为准则。通过参与，你应该遵守这个准则。总的来说，我们努力遵守开源软件开发中普遍接受的最佳实践。

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

版权

版权所有 © 2019年起 fast.ai, Inc. 根据Apache License, Version 2.0（"许可证"）获得许可；除非符合许可证，否则你不得使用此项目的文件。许可证的副本在本仓库的LICENSE文件中提供。