# Directives


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Directives are special comments that are preceded by `#|` that control:

1.  Cell visibility in rendered documentation
2.  How source code is generated from notebook cells
3.  Execution of cells for tests and docs

nbdev augments [Quarto](https://quarto.org/) by providing additional
directives than what are available in Quarto. [All Quarto
directives](https://quarto.org/docs/reference/cells/cells-jupyter.html)
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](https://quarto.org/docs/reference/cells/cells-jupyter.html) to see
all of the directives available to you.

To clarify the origin of directives we use the following emojis:

- 📓 for nbdev-only directives .
- 🔵 for Quarto directives (which also work in nbdev).

## Cell Visibility

The following directives control cell visibility in rendered
documentation:

### 📓 `#| hide`

Hide cell input and output.

<div>

> **Example**
>
> The following will result in the contents of the cell and it’s output
> from being hidden:
>
> ``` python
> #| hide
> print('you will not see this')
> ```
>
> Note that using `#| hide` is equivalent to using the Quarto directive
> `#| include: false`:
>
> ``` python
> #| include: false
> print('you will not see this')
> ```
>
> See the quarto docs for more information about `#| include`.

</div>

### 🔵 `#| echo: <true|false>`

Toggle the visibility of code-cell inputs.

<div>

> **Example**
>
> ``` python
> #| echo: false
> print('you can see the output but not the code!')
> ```
>
> which results in:
>
>     you can see the output but not the code!

</div>

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

Setting this to `false` hides the output of a cell. Setting this to
`asis` renders the output as raw markdown.

<div>

> **Example**
>
> The following cell will not display any output:
>
> ``` python
> #| output: false
> 1 + 1
> ```
>
> The following cell with `#| output: asis` will produce the output
> `hello fastai` rendered as markdown instead of a string:
>
> ``` python
> #| output: asis
> print("`hello fastai`")
> ```

</div>

### 📓 `#| hide_line`

Hide a specific line of code in an input cell.

<div>

> **Example**
>
> ``` python
> def _secret(): ...
>
> for i in range(3):
>     _secret() #| hide_line
>     print(i)
> ```
>
> becomes this:
>
> ``` python
> def _secret(): ...
>
> for i in range(3):
>     print(i)
> ```
>
>     0
>     1
>     2

</div>

### 📓 `#| filter_stream <keyword> ...`

Filter lines containing specific keywords in cell outputs.

<div>

> **Example**
>
> ``` python
> #| filter_stream FutureWarning MultiIndex
> print('\n'.join(['A line', 'Foobar baz FutureWarning blah', 
>                  'zig zagMultiIndex zoom', 'Another line.']))
> ```
>
> will output this:
>
>     A line
>     Another line.

</div>

### 🔵 `#| 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.

<div>

> **Example**
>
> When you set `#| code-fold: true`, the input cell is collapsed:
>
> <details class="code-fold">
> <summary>Code</summary>
>
> ``` python
> print('this is')
> print('output')
> print('that takes')
> print('lots of vertical space')
> ```
>
> </details>
>
>     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:
>
> <details open class="code-fold">
> <summary>Code</summary>
>
> ``` python
> print('this is')
> print('output')
> print('that takes')
> print('lots of vertical space')
> ```
>
> </details>
>
>     this is
>     output
>     that takes
>     lots of vertical space

</div>

## Generating Source Code

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.

<div>

> **Example**
>
> ``` python
> #| default_exp baz
>
> # In a new notebook cell:
>
> #| export
> def my_function(): pass
> ```
>
> If our package is named: `bitsnbytes` then we can do:
>
> ``` python
> from bitsnbytes.baz import my_function
> ```
>
> The package name is defined by `name` in `[project]` in
> `pyproject.toml`.

</div>

### 📓 `#| export`

Exports the items in the cell into the generated module and
documentation.

<div>

> **Example**
>
> ``` python
> #| 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__`](https://docs.python.org/3/tutorial/modules.html#importing-from-a-package)
> 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:
>
> ------------------------------------------------------------------------
>
> ### say_hello
>
> ``` python
>
> def say_hello(
>     to:str, # name of person to say hello to
> ):
>
> ```
>
> *Say hello to somebody*
>
> The docs are generated from this export using
> [`show_doc`](https://nbdev.fast.ai/api/showdoc.html#show_doc). See
> [these docs](docs.ipynb#how-show_doc-works) for a detailed discussion
> of [`show_doc`](https://nbdev.fast.ai/api/showdoc.html#show_doc).

</div>

### 📓 `#| exporti`

An `i`nternal export. [Not included in
`__all__`](https://docs.python.org/3/tutorial/modules.html#importing-from-a-package)
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.

<div>

> **Example**
>
> ``` python
> #| exports
> def say_hello(to):
>     "Say hello to somebody"
>     return f'Hello {to}!'
> ```
>
> this will produce the following output:
>
> ``` python
> def say_hello(to):
>     "Say hello to somebody"
>     return f'Hello {to}!'
> ```
>
> ------------------------------------------------------------------------
>
> ### say_hello
>
> ``` python
>
> def say_hello(
>     to
> ):
>
> ```
>
> *Say hello to somebody*

</div>

## Cell Execution

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](https://nbdev.fast.ai/explanations/docs.html).

<div>

> **Example**
>
> ``` python
> datetime.datetime.now()
> ```
>
>     datetime.datetime(2022, 8, 18, 9, 1, 43, 907609)
>
> However with the annotation:
>
> ``` python
> #| exec_doc
> datetime.datetime.now()
> ```
>
> we can see that the time has been updated:
>
> ``` python
> datetime.datetime.now()
> ```
>
>     datetime.datetime(2026, 5, 21, 3, 15, 8, 972912)

</div>

### 🔵 `#| eval: <true|false>`

When set to `false`, the cell is ignored during testing.

<div>

> **Example**
>
> ``` python
> #| eval: false
> raise Exception("I'm not raised because I'm not run")
> ```

</div>

### Cell execution when there is no directive

When a cell has no directives, cells are run by nbdev according to the
behavior [described here](docs.ipynb#automatic-cell-execution).