nbdev uses special comments as a markup language that allows you to control various aspects of the documentation, how code is exported to modules, and how code is tested.
nbdev comments for exporting cells to modules.
#default_exp module_name specifies that code exported from this notebook will be placed in the destination "module_name.py" module.
. for submodules and do not include the
.py file extension. For example,
#default_exp module.submodule sets the destination module to "module/submodule.py"
If specific cells need to be exported to a different module, indicate it after #export:
- To add something to
__all__if it's not picked automatically, write an exported cell with something like
#add2all "my_name". If you are not familiar with what
__all__is used for, have a look at this link.
#export to each cell you want to be included in your module and the documentation. When no argument is provided to export, this defaults to the module specified by
#default_exp as described above.
a cell marked with
#export will have its signature added to the documentation.
#export class S1(): def __init__(self, *args, **kwargs): pass
#exports is just like
#export but will additionally have the source code added to the documentation.
#exports class S2(): def __init__(self, *args, **kwargs): pass
class S2(): def __init__(self, *args, **kwargs): pass
#exporti for each cell you want exported without it being added to
__all__, and without it showing up in the docs.
#exporti class S3(): def __init__(self, *args, **kwargs): pass
nbdev comments for hiding cells, inputs, or outputs.
This comment instructs nbdev to hide the cell when generating the docs.
#hide_input at the top of a cell if you don't want code to be shown in the docs.
show_doc have their code hidden automatically.
This is output. Input is hidden using #hide_input
#hide_output at the top of a cell if you don't want output to be shown in the docs.
print("This is input. Output is hidden using #hide_output")
nbdev comments for having inputs or outputs under a collapsable element.
#collapse to include code in the docs under a collapsable element. The collapsable element is closed by default.
print("This is output. Input is collapsed using #collapse")
This is output. Input is collapsed using #collapse
#collapse_show in a code cell will include your code under a collapsable element that is open by default.
print("This is output. Input can be collapsed using #collapse_show")
This is output. Input can be collapsed using #collapse_show
#collapse_output to include output in the docs under a collapsable element.
print("Output is collapsed using #collapse_output")
Output is collapsed using #collapse_output
This defines the default level of classes in the table of contents (TOC). Use
#default_cls_lvl followed by a number to se the level (default is 2).
above cell changes the level of classes in this notebook to 4. Check TOC at the top of this page.
Everything that is not an exported cell is considered a test, so you should make sure your notebooks can all run smoothly (and fast) if you want to use this functionality as the CLI. You can mark some cells with special flags (like
#slow) to make sure they are only executed when you authorize it. Those flags should be configured in your settings.ini (separated by a
| if you have several of them). You can also apply flags to one entire notebook by using the
all option, e.g.
#all_slow, in code cells.
tst_flags=slow|fastai in settings.ini, you can:
- mark slow tests with
- mark tests that depend on fastai with the