Overview

nbdev is progressively getting magic commands that will eventually replace the special comments it currently uses, so you get autocomplete and documentation:

magic animation

You'll also get feedback when flags are used incorrectly:

magic usage error

How do I start using magic flags?

Grab an editable install of nbdev then run nbdev_upgrade from the command line - this will update notebooks that use comment flags like:

#export special.module

to use magic flags:

%nbdev_export special.module

To make magic flags work, nbdev_upgrade might need to add a new code cell to the top of the notebook:

from nbdev import *

You can run nbdev_upgrade any number of times - which means you can update the same project every time new magic flags get added to nbdev.

Can I use both comment and magic flags?

Both comment and magic flags are currently supported and you can use both kinds in the same notebook.

Why can't I see any "test" flags?

If you don't see the test flags you need ...

auto complete no test

... you'll probably need to update settings.ini then restart your notebook.

Test flags are configured in your settings.ini (set tst_flags, separating flags by a | if you have several of them).

When the nbdev.flags module is imported, test flags are created dynamically from your settings.ini. If tst_flags=slow|gpu, the following flags would be available:

%nbdev_slow_test
%nbdev_gpu_test

Can I use flags in any kind of cell?

Apart from #hide and %nbdev_hide, nbdev will ignore flags that are not in code cells. This means that you can use markdown cells for "developer-only" details and #hide them from the HTML docs.

Do magic flags work differently to comment flags?

Ideally, they would work the same but ... there is a difference when nbdev splits the source of a cell into flags and code;

If no magic flags are found, treat the first comment line as a flag

split_flags_and_code example

If magic flags are found, the flags part can contain multiple lines

split_flags_and_code example

This could make a difference because nbdev writes just the code part to both your library and HTML docs.

How do comment flags correspond to magic flags?

Comment flag Magic flag
default_exp nbdev_default_export Define the name of the module everything should be exported in
exports nbdev_export_and_show Export and show code in the docs
exporti nbdev_export_internal Export but don’t show in docs and don’t add to __all__
export nbdev_export Export but don’t show in docs
hide_input nbdev_hide_input Do not show input of a test cell in docs
hide_output nbdev_hide_output Do not show output of a test cell in docs
hide nbdev_hide Do not show a test cell or markdown in docs
default_cls_lvl nbdev_default_class_level Define the default toc level of classes
collapse_output or collapse-output nbdev_collapse_output Inlcude output in the docs under a collapsable element
collapse_show or collapse-show nbdev_collapse_input open Inlcude intput in the docs under a collapsable element that is open by default
collapse_hide or collapse-hide nbdev_collapse_input Inlcude intput in the docs under a collapsable element
collapse nbdev_collapse_input Inlcude intput in the docs under a collapsable element

Why might we add magic flags for _all_ and show_doc?

One of the reasons for suggesting this is so that everything can be done via magic flags - rather than using flags for everything except _all_ and show_doc.

%nbev_add2__all__

here's what we do today

_all_ = ['progress_bar','master_bar']

but we could ...

%nbev_add2__all__ progress_bar,master_bar

This flag could

  • check that everything exists and names are valid (when the cell is executed) and
  • make it possible to tab-complete the items you're adding to __all__

add to all

The example above uses a line magic, so you'd have to move everything on line 3 up to line 2 but ... we could use a cell magic

%nbev_show_doc

here's what we do today

# nbdev removes show_doc cells, so we need to use a alias 
show__doc = show_doc
show__doc(ArithmeticError)

class ArithmeticError[source]

ArithmeticError() :: Exception

Base class for arithmetic errors.

show__doc(ArithmeticError.mro)

ArithmeticError.mro[source]

ArithmeticError.mro()

Return a type's method resolution order.

show__doc(ArithmeticError.__init__)

ArithmeticError.__init__[source]

ArithmeticError.__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

but we could ...

%nbev_show_doc ArithmeticError mro __init__

class ArithmeticError[source]

ArithmeticError() :: Exception

Base class for arithmetic errors.

ArithmeticError.mro[source]

ArithmeticError.mro()

Return a type's method resolution order.

ArithmeticError.__init__[source]

ArithmeticError.__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

This flag could make it possible to "show doc" a class and any number of its methods with a single line of code.