文学式编程-nbdev入门教程

nbdev是一个使用Jupyter Notebook进行多模块软件开发的辅助工具，可以将多个Notebook组装为一个大型的软件系统，自动生成代码和文档，并能够在Notebook中进行交互运行和探索性测试。

• nbdev 源码：https://github.com/fastai/nbdev

• nbdev 文档：https://nbdev.fast.ai/

nbdev主要完成下面的功能：

• 建立python开发框架和git repo版本。
• 在notebook中的cell中使用#export标记为输出代码区块。
• 使用库函数notebook2script()将#export标记的代码转化为python库*.py。

• 所生成的代码放在project name的目录下，可以在notebook中引用或者直接运行。

• 例程项目，用于nCoV分析（初级阶段）：https://github.com/openthings/anti2020ncov

1、安装

nbdev已经加入 PyPI，使用下面的命令安装：

pip install nbdev

对于 editable install，使用：

git clone https://github.com/fastai/nbdev
pip install -e nbdev

2、快速开始

2.1 创建项目

开始自己的 project, 点击: nbdev template (会要求登录到 GitHub )。填写要求的信息，然后点击 Create repository from template, 新的 GitHub repo将会在你的账户下创建出来。

注意: 项目的名称将成为 Python package的名称，由 nbdev 自动创建。建议选择短的全部小写而且没有连接线的名称（下划线可以）。

现在，打开终端，将该 repo 拉去到本地（git clone ...），可以使用Jupyter里面创建的终端窗口。

可选方式，可以使用nbdev的客户端命令 nbdev_new 来创建nbdev project，并且初始化git repository到本地，不会创建 github repo。

2.2 设置参数

下一步，编辑 settings.ini 文件。

该文件包含所有的打包你的库的信息因此不需要改变 setup.py 文件，这是由模版工程创建的。基本结构 (that can be personalized provided you change the relevant information in settings.ini) 是 repo的根目录将包含你的 notebooks, 目录 docs 包含文档是自动创建的，可用于 jekyll-powered 站点。因为 GitHub Pages supports Jekyll, 可以将该文档放到 GitHub ，不需要做任何额外的设置。

你的 settings.ini 放在 nbdev，用于任何需要的配置信息。如果编辑了该文件，运行命令 nbdev_build_lib (安装 nbdev时自动安装）。 你将发现有了一个新的新的目录，按照 lib_name 在 settings.ini中的设置。

现在运行jupyter notebook, 点击 00_core.ipynb。 这是你创建的第一个模块。可以在notebook中创建多个Jupyter cells。 在需要包含在python模块的cell最前面加上 #export ，必须是第一行。

• 注意：
  • 对于新创建的 .ipynb，需要加入 #default_exp target_module_name, 用于定义创建的模块名称(lib_name/target_module_name.py)。

在notebook的最后一个cell，可以运行下面的函数调用，用于创建*.py文件。

from nbdev.export import *
notebook2script()

Converted 00_export.ipynb.
Converted 01_sync.ipynb.
Converted 02_showdoc.ipynb.
Converted 03_export2html.ipynb.
Converted 04_test.ipynb.
Converted 05_merge.ipynb.
Converted 06_cli.ipynb.
Converted 07_clean.ipynb.
Converted 99_search.ipynb.
Converted index.ipynb.
Converted tutorial.ipynb.

或者在命令行下运行命令：

nbdev_build_lib

将会更新模块，包含所有的exported cells。

为了在 GitHub repo启用文档功能，到github.com的项目中点击 'Settings' ，到 'GitHub Pages', 在 'Source' 选择'master branch /docs folder'。GitHub 将现实文档站点的连接。

最后，编辑 edit index.ipynb。该页面将转化为项目文档的 README 文件，也是你的文档的索引。你可以使用输出库中的模块，意味着可以显示正式的工作代码和实际输出。一旦准备好了，到命令行运行 nbdev_build_docs，将输出将notebook输出到 HTML 版本并保存到 docs 目录。同时将创建链接，创建所有notebook的菜单，以及内容的目录表等。

注意，如何使用子目录保存 .ipynb 文件

如果你设置过参数 nbs_path 在 project root之外，将不能 import 创建的模块，需要一些额外的操作：

• 手动安装模块， relative import 将与top-level package关联，通过运行 pip install -e . 在项目根目录，安装模块到环境中。
• 创建软连接到notebook 目录到library folder，通过运行 ln -s lib_path lib_name (修改lib_path 和lib_name为你的项目情况).

其它功能

nbdev还有很多其他功能，查看相应的文档。下面简单提一下：

添加project 到 pypi

如果你希望其他人可以通过pypi来进行安装，需要将其提交到 pypi。好消息是，我们已经创建了一个 pypi compliant installer for your project!创建一个文件为 ~/.pypirc 填入登录信息。内容看起来如下所示：

[pypi]
username = your_pypi_username
password = your_pypi_password

需要安装 twine，运行：

pip install twine

上载 project 到pypi，只需要运行 make pypi ，在 project root 目录下。完成后，指向 pypi 的连接会被打印出来。

NB: 确保每一次增加 version number，位于 settings.py ，用于向pypi推送一个新的版本。

避免和处理 git conflicts

Jupyter Notebooks 会引起 git conflicts, 但使用 nbdev就要轻松很多。 第一步，运行 nbdev_install_git_hooks将设置 git hooks，每一次commit时会移除元数据，会极大减少 conflict。

但是，如果遇上 conflict, 简单滴运行 nbdev_fix_merge filename.ipynb. 将用你的版本替换任何 conflicts in cell outputs , 如果 conflicts in input cells，两个 cells 都将被包含在 merged file, 使用标准的冲突标示 (e.g. =====)。然后你可以打开 notebook到 Jupyter，然后选择保留哪一个。

使用nbdev作为 CI的一部分

可以使用 GitHub actions 来提升 nbdev的功能，容易滴构建 CI ：

• 检查 notebooks are readable (with nbdev_read_nbs)
• 检查the notebooks have been cleaned of needless metadata to avoid merge conflicts (with nbdev_clean_nbs)
• 检查there is no diff between the notebooks and the exported library (with nbdev_diff_nbs)
• 运行notebooks 中的测试(with nbdev_test_nbs)

该template 包含基本的 CI，使用了上面四点，编辑文件 .github/workflows/main.yml 修改相关的部分。

Math 公式支持

nbdev 支持公式 (采用 KaTeX library)。使能 use_math: true 到your _config.yml (缺省已开启)。应用方法如下：

使用$$, e.g.:

$$\sum_{i=1}^{k+1}i$$

显示为：

$$\sum_{i=1}^{k+1}i$$

使用$, e.g.:

This version is diplayed inline: $\sum_{i=1}^{k+1}i$ . You can include text before and after.

显示为：

This version is diplayed inline: $\sum_{i=1}^{k+1}i$ . You can include text before and after.

 

更多参考：

• 关于nbdev的介绍，https://tech.sina.com.cn/roll/2020-02-03/doc-iimxxste8470190.shtml
• 运用Jupyter Notebook进行系统管理
• 将Jupyter/JupyterHub/JupyterLab运行为系统服务
• 快速设置JupyterHub for K8s
• 抗击新冠病毒（2）-基于Jupyter+nbdev的数据分析

来源：oschina

链接：https://my.oschina.net/u/2306127/blog/3163740