#|hide
from fastcore.test import *
from nbdev.showdoc import show_doc
A cheat sheet of directives available in nbdev.
Directives are special comments that are preceded by #|
that control:
nbdev augments Quarto by providing additional directives than what are available in Quarto. All Quarto directives can be used in nbdev notebooks.
This cheat sheet lists all nbdev directives in addition to some Quarto directives we believe are important. We recommend consulting the quarto docs to see all of the directives available to you.
To clarify the origin of directives we use the following emojis:
The following directives control cell visibility in rendered documentation:
#|hide
¶Hide cell input and output.
::: {.callout-note collapse="true"}
The following will result in the contents of the cell and it's output from being hidden:
#|hide
print('you will not see this')
Note that using #|hide
is equivalent to using the Quarto directive #|include: false
:
#|include: false
print('you will not see this')
See the quarto docs for more information about #|include
.
:::
#|output: <true|false|asis>
¶Setting this to false
hides the output of a cell. Setting this to asis
renders the output as raw markdown.
::: {.callout-note collapse="true"}
The following cell will not display any output:
#|output: false
1 + 1
The following cell with #|output: asis
will produce the output hello fastai
rendered as markdown instead of a string:
#|output: asis
print("`hello fastai`")
:::
def _secret(): ...
for i in range(3):
_secret() #|hide_line
print(i)
0 1 2
:::
#|echo: false
#|filter_stream FutureWarning MultiIndex
print('\n'.join(['A line', 'Foobar baz FutureWarning blah',
'zig zagMultiIndex zoom', 'Another line.']))
A line Foobar baz FutureWarning blah zig zagMultiIndex zoom Another line.
:::
#|code-fold: <show|true>
¶The #|code-fold
directive allows you to collapse code cells. When set to true
, the element is collapsed by default, when set to show show
the element is shown by default.
::: {.callout-note collapse="true"}
When you set #|code-fold: true
, the input cell is collapsed:
#|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
When you set #|code-fold: show
the input cell is shown but still in a collapsible element:
#|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
:::
The following directives control how source code is exported from code cells.
#|default_exp <name>
¶Names the module where cells with the #|export
directive will be exported to by default.
::: {.callout-note collapse="true"}
#| default_exp baz
# In a new notebook cell:
#| export
def my_function(): pass
If our package is named: bitsnbytes
then we can do:
from bitsnbytes.baz import my_function
You can define the package name by using lib_name
in settings.ini
.
:::
#|export
¶Exports the items in the cell into the generated module and documentation.
::: {.callout-note collapse="true"}
#|export
def say_hello(to:str # name of person to say hello to
):
"Say hello to somebody"
return f'Hello {to}!'
The above cell will get exported to the module specified by #|default_exp
. These exports are automatically included in __all__
for the module. To learn how export without inclusion in __all__
, see the #|exporti
directive.
Furthermore, the documentation for this function will automatically be rendered like this:
#|exec_doc
#|echo: false
def say_hello(to:str # name of person to say hello to
):
"Say hello to somebody"
return f'Hello {to}!'
#|echo: false
# Note: we are using show_doc like this to simulate the effect of #|export without using export
show_doc(say_hello)
say_hello (to:str)
Say hello to somebody
Type | Details | |
---|---|---|
to | str | name of person to say hello to |
The docs are generated from this export using show_doc
. See these docs for a detailed discussion of show_doc
.
:::
#|export <some.thing>
¶Similar to #|export
, but instead of exporting to the module named by #|default_exp
export to the specified module.
::: {.callout-note collapse="true"}
If our package is named: bitsnbytes
, and we have previously included: #|default_exp core
in this notebook, and we have an existing notebook with #|default_exp bar
, then:
Earlier in the notebook:
#|default_exp core
A new notebook cell:
#|export bar
def foo(): pass
then we can import this as:
from bitsnbytes.bar import foo
:::
#|exporti
¶An i
nternal export. Not included in __all__
or the docs. Useful for a function that is called by other functions in this module but is not part of the public API.
Equivalently, you can prefix your function or method with _
e.g. def _private(): pass
.
#|exports
¶A s
ource export. Like #|export
but in addition to showing docs via showdoc.show_doc
, it also shows the source code.
::: {.callout-note collapse="true"}
#|exports
def say_hello(to):
"Say hello to somebody"
return f'Hello {to}!'
this will produce the following output:
#|exec_doc
#|echo: true
def say_hello(to):
"Say hello to somebody"
return f'Hello {to}!'
#|echo: false
show_doc(say_hello)
:::
The following directives allow you to control how cells are executed during docs rendering and testing.
#|exec_doc
¶Ensures that a cell is executed each time before generating docs. When a cell does not have this annotation, it is run according to the default rules described here.
::: {.callout-note collapse="true"}
#|hide
import datetime
datetime.datetime.now()
datetime.datetime(2022, 8, 18, 9, 1, 43, 907609)
However with the annotation:
#|exec_doc
datetime.datetime.now()
we can see that the time has been updated:
#|exec_doc
datetime.datetime.now()
datetime.datetime(2022, 8, 18, 9, 1, 43, 911506)
:::
#|eval: <true|false>
¶When set to false
, the cell is ignored during testing.
::: {.callout-note collapse="true"}
#|eval: false
raise Exception("I'm not raised because I'm not run")
:::
When a cell has no directives, cells are run by nbdev according to the behavior described here.