开始使用
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的最佳方式是完成书面教程或观看视频教程:
另外,还有一个视频教程的缩短版本,使用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文件中提供。