nbagile

使nbdev更敏捷友好

安装

pip install nbagile

目标

• 当使用docments导出源代码时，将附上并格式化docstring为Numpy格式
• 导出测试并将其转换为pytest兼容的文件格式
• 使文档能在Sphynx上运行
• 测试被导出到tests文件夹，源代码到源代码文件夹，Markdown/Sphynx文档到docs文件夹
• 然后可以从这三个项目重新创建单个notebook

当前功能

使用CLI

将nbdev_命令替换为nbagile_以使用其功能。 当前支持

• nbagile_build_lib：导出代码并将其转换为black-style + NumPy docstrings
• nbagile_diff_nbs：一个特殊的nbdev_diff_nbs版本，以支持nbagile的工作方式
• nbagile_build_docs：使用nbverbose构建文档

从docments导出代码到NumPy

docments 是一种非常高效的代码参数文档方式，类似于javascript的文档方式。我们利用注释块和typing来描述参数的用法。例如，我们有以下内容

def addition(
    a:int, # The first number to add
    b:(int,float), # The second number to add
) -> int: # The sum of a and b
    "Adds a and b"
    return a+b

但这并不是我们通常接受的方式来记录代码，整体看起来相当难看。

nbagile 支持构建你的 nbdev 构建的库，自动将此代码转换为更符合 NumPy 风格的文档字符串和定义，并且额外提供模仿 Black 格式的功能。

def addition(a,b):
    """Adds a and b
    
    Parameters
    ----------
    a : int
      The first number to add
    b : (int,float)
      The second number to add
      
    Returns
    ----------
    int
      The sum of a and b
    """
    return a+b

这适用于函数、类以及装饰器包装的函数。

nbdev 的可选 __all__

如果你不喜欢每个文件中 nbdev 的 __all__ 格式，你可以将额外的设置添加到你的 settings.ini：use_all。

如果设置为 False，你不会在每个 Python 文件中生成 __all__