指令

nbdev 中可用指令的速查表。

指令是特殊的注释，以 #| 开头，它们控制

1. 渲染文档中单元格的可见性
2. 如何从 notebook 单元格生成源代码
3. 用于测试和文档的单元格执行

nbdev 增强了 Quarto，提供了比 Quarto 更多额外的指令。所有 Quarto 指令 都可以在 nbdev notebook 中使用。

本速查表列出了所有 nbdev 指令，以及我们认为重要的 Quarto 指令。我们建议查阅 quarto 文档 以查看所有可用的指令。

为了阐明指令的来源，我们使用以下表情符号

• 📓 表示仅 nbdev 指令。
• 🔵 表示 Quarto 指令（也适用于 nbdev）。

单元格可见性

以下指令控制渲染文档中单元格的可见性

📓 #|hide

隐藏单元格输入和输出。

示例

以下指令将导致单元格内容及其输出被隐藏

#|hide
print('you will not see this')

请注意，使用 #|hide 等同于使用 Quarto 指令 #|include: false

#|include: false
print('you will not see this')

有关 #|include 的更多信息，请参阅 quarto 文档。

🔵 #|echo: <true|false>

切换代码单元格输入的可见性。

示例

#|echo: false
print('you can see the output but not the code!')

结果是

you can see the output but not the code!

🔵 #|output: <true|false|asis>

将其设置为 false 会隐藏单元格的输出。将其设置为 asis 会将输出渲染为原始 markdown。

示例

以下单元格将不显示任何输出

#|output: false
1 + 1

以下带有 #|output: asis 指令的单元格将产生输出 hello fastai，它会渲染为 markdown 而不是字符串

#|output: asis
print("`hello fastai`")

📓 #|hide_line

隐藏输入单元格中的特定代码行。

示例

def _secret(): ...

for i in range(3):
    _secret() #|hide_line
    print(i)

变成这样

def _secret(): ...

for i in range(3):
    print(i)

0
1
2

📓 #|filter_stream <keyword> ...

过滤包含单元格输出中特定关键字的行。

示例

#|filter_stream FutureWarning MultiIndex
print('\n'.join(['A line', 'Foobar baz FutureWarning blah', 
                 'zig zagMultiIndex zoom', 'Another line.']))

将输出

A line
Another line.

🔵 #|code-fold: <show|true>

#|code-fold 指令允许您折叠代码单元格。当设置为 true 时，元素默认折叠；当设置为 show 时，元素默认显示。

示例

当您设置 #|code-fold: true 时，输入单元格会折叠

print('this is')
print('output')
print('that takes')
print('lots of vertical space')

this is
output
that takes
lots of vertical space

当您设置 #|code-fold: show 时，输入单元格会显示，但仍在可折叠元素中

print('this is')
print('output')
print('that takes')
print('lots of vertical space')

this is
output
that takes
lots of vertical space

生成源代码

以下指令允许您控制如何从代码单元格导出源代码。

📓 #|default_exp <name>

命名带有 #|export 指令的单元格默认导出的模块。

示例

#| default_exp baz

# In a new notebook cell:

#| export
def my_function(): pass

如果我们的包名为：bitsnbytes，那么我们可以这样做

from bitsnbytes.baz import my_function

您可以通过在 settings.ini 中使用 lib_name 来定义包名。

📓 #|export

将单元格中的项导出到生成的模块和文档中。

示例

#|export
def say_hello(to:str # name of person to say hello to
             ):
    "Say hello to somebody"
    return f'Hello {to}!'

上面的单元格将导出到由 #|default_exp 指定的模块。这些导出会自动包含在模块的 __all__ 中。要了解如何在不包含在 __all__ 中的情况下导出，请参阅 #|exporti 指令。

此外，此函数的文档将自动渲染如下

---

say_hello

 say_hello (to:str)

向某人问好

	类型	详情
to	str	要问好的人名

文档是使用 show_doc 从此导出生成的。有关 show_doc 的详细讨论，请参阅 这些文档。

📓 #|exporti

一个 internal (内部) 导出。不包含在 __all__ 或文档中。适用于在此模块中被其他函数调用但不属于公共 API 的函数。

同样，您也可以在函数或方法前加上 _ 前缀，例如 def _private(): pass。

📓 #|exports

一个 source (源) 导出。类似于 #|export，但除了通过 showdoc.show_doc 显示文档外，还会显示源代码。

示例

#|exports
def say_hello(to):
    "Say hello to somebody"
    return f'Hello {to}!'

这将产生以下输出

def say_hello(to):
    "Say hello to somebody"
    return f'Hello {to}!'

---

say_hello

 say_hello (to)

向某人问好

单元格执行

以下指令允许您控制在文档渲染和测试期间如何执行单元格。

📓 #|exec_doc

确保在生成文档之前每次都执行单元格。当单元格没有此注释时，它将按照此处描述的默认规则运行。

示例

datetime.datetime.now()

datetime.datetime(2022, 8, 18, 9, 1, 43, 907609)

然而，有了此注释

#|exec_doc
datetime.datetime.now()

我们可以看到时间已更新

datetime.datetime.now()

datetime.datetime(2025, 4, 3, 1, 2, 11, 826215)

🔵 #|eval: <true|false>

当设置为 false 时，单元格在测试期间将被忽略。

示例

#|eval: false
raise Exception("I'm not raised because I'm not run")

没有指令时的单元格执行

当单元格没有指令时，nbdev 会按照此处描述的行为运行单元格。