nbs/explanations/directives.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "from fastcore.test import *\n",
    "from nbdev.showdoc import show_doc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Directives\n",
    "\n",
    "> A cheat sheet of directives available in nbdev.\n",
    "- order: 2\n",
    "- callout-appearance: simple\n",
    "- toc-depth: 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Directives are special comments that are preceded by `#|` that control:\n",
    "\n",
    "1. Cell visibility in rendered documentation\n",
    "2. How source code is generated from notebook cells\n",
    "3. Execution of cells for tests and docs\n",
    "\n",
    "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.  \n",
    "\n",
    "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.\n",
    "\n",
    "To clarify the origin of directives we use the following emojis:\n",
    "\n",
    "- 📓 for nbdev-only directives .\n",
    "- 🔵 for Quarto directives (which also work in nbdev)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cell Visibility\n",
    "\n",
    "The following directives control cell visibility in rendered documentation:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|hide`  \n",
    "\n",
    "Hide cell input and output. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "The following will result in the contents of the cell and it's output from being hidden:\n",
    "\n",
    "```python\n",
    "#|hide\n",
    "print('you will not see this')\n",
    "```\n",
    "\n",
    "Note that using `#|hide` is equivalent to using the Quarto directive `#|include: false`:\n",
    "\n",
    "```python\n",
    "#|include: false\n",
    "print('you will not see this')\n",
    "```\n",
    "\n",
    "See the quarto docs for more information about `#|include`.\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 🔵 `#|echo: <true|false>`\n",
    "\n",
    "Toggle the visibility of code-cell inputs.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "#|echo: false\n",
    "print('you can see the output but not the code!')\n",
    "```\n",
    "\n",
    "    \n",
    "which results in:\n",
    "    \n",
    "    \n",
    "```\n",
    "you can see the output but not the code!\n",
    "```\n",
    "    \n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 🔵 `#|output: <true|false|asis>`\n",
    "\n",
    "Setting this to `false` hides the output of a cell. Setting this to `asis` renders the output as raw markdown.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "  \n",
    "The following cell will not display any output:\n",
    "\n",
    "```python\n",
    "#|output: false\n",
    "1 + 1\n",
    "```\n",
    "    \n",
    "The following cell with `#|output: asis` will produce the output `hello fastai` rendered as markdown instead of a string:  \n",
    "    \n",
    "```python    \n",
    "#|output: asis\n",
    "print(\"`hello fastai`\")\n",
    "```         \n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|hide_line`\n",
    "\n",
    "Hide a specific line of code in an input cell.  \n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "def _secret(): ...\n",
    "\n",
    "for i in range(3):\n",
    "    _secret() #|hide_line\n",
    "    print(i)\n",
    "```\n",
    "\n",
    "becomes this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\n",
      "1\n",
      "2\n"
     ]
    }
   ],
   "source": [
    "def _secret(): ...\n",
    "\n",
    "for i in range(3):\n",
    "    _secret() #|hide_line\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|filter_stream <keyword> ...`\n",
    "\n",
    "Filter lines containing specific keywords in cell outputs.  \n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "\n",
    "```python\n",
    "#|filter_stream FutureWarning MultiIndex\n",
    "print('\\n'.join(['A line', 'Foobar baz FutureWarning blah', \n",
    "                 'zig zagMultiIndex zoom', 'Another line.']))\n",
    "```\n",
    "\n",
    "will output this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A line\n",
      "Foobar baz FutureWarning blah\n",
      "zig zagMultiIndex zoom\n",
      "Another line.\n"
     ]
    }
   ],
   "source": [
    "#|echo: false\n",
    "#|filter_stream FutureWarning MultiIndex\n",
    "print('\\n'.join(['A line', 'Foobar baz FutureWarning blah', \n",
    "                 'zig zagMultiIndex zoom', 'Another line.']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 🔵 `#|code-fold: <show|true>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "When you set `#|code-fold: true`, the input cell is collapsed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "this is\n",
      "output\n",
      "that takes\n",
      "lots of vertical space\n"
     ]
    }
   ],
   "source": [
    "#|code-fold: true\n",
    "\n",
    "print('this is')\n",
    "print('output')\n",
    "print('that takes')\n",
    "print('lots of vertical space')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you set `#|code-fold: show` the input cell is shown but still in a collapsible element:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "this is\n",
      "output\n",
      "that takes\n",
      "lots of vertical space\n"
     ]
    }
   ],
   "source": [
    "#|code-fold: show\n",
    "\n",
    "print('this is')\n",
    "print('output')\n",
    "print('that takes')\n",
    "print('lots of vertical space')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating Source Code\n",
    "\n",
    "The following directives control how source code is exported from code cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|default_exp <name>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Names the module where cells with the `#|export` directive will be exported to by default.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "#| default_exp baz\n",
    "\n",
    "# In a new notebook cell:\n",
    "\n",
    "#| export\n",
    "def my_function(): pass\n",
    "```\n",
    "\n",
    "If our package is named: `bitsnbytes` then we can do:\n",
    "\n",
    "```python\n",
    "from bitsnbytes.baz import my_function\n",
    "```\n",
    "\n",
    "You can define the package name by using `lib_name` in `settings.ini`.\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|export`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Exports the items in the cell into the generated module and documentation. \n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "#|export\n",
    "def say_hello(to:str # name of person to say hello to\n",
    "             ):\n",
    "    \"Say hello to somebody\"\n",
    "    return f'Hello {to}!'\n",
    "```\n",
    "\n",
    "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.\n",
    "\n",
    "Furthermore, the documentation for this function will automatically be rendered like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#|exec_doc\n",
    "#|echo: false\n",
    "def say_hello(to:str # name of person to say hello to\n",
    "             ):\n",
    "    \"Say hello to somebody\"\n",
    "    return f'Hello {to}!'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### say_hello\n",
       "\n",
       ">      say_hello (to:str)\n",
       "\n",
       "Say hello to somebody\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| to | str | name of person to say hello to |"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### say_hello\n",
       "\n",
       ">      say_hello (to:str)\n",
       "\n",
       "Say hello to somebody\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| to | str | name of person to say hello to |"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|echo: false\n",
    "# Note: we are using show_doc like this to simulate the effect of #|export without using export\n",
    "show_doc(say_hello)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The docs are generated from this export using `show_doc`. See [these docs](docs.ipynb#how-show_doc-works) for a detailed discussion of `show_doc`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|export <some.thing>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to `#|export`, but instead of exporting to the module named by `#|default_exp` export to the specified module.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "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:\n",
    "\n",
    " Earlier in the notebook:\n",
    "\n",
    "```python\n",
    "#|default_exp core\n",
    "```\n",
    "\n",
    "A new notebook cell:\n",
    "\n",
    "```python\n",
    "#|export bar\n",
    "def foo(): pass\n",
    "```\n",
    "\n",
    "then we can import this as:\n",
    "\n",
    "```python\n",
    "from bitsnbytes.bar import foo\n",
    "```\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|exporti`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.  \n",
    "\n",
    "Equivalently, you can prefix your function or method with `_` e.g. `def _private(): pass`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|exports`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `s`ource export. Like `#|export` but in addition to showing docs via `showdoc.show_doc`, it also shows the source code.\n",
    "\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "#|exports\n",
    "def say_hello(to):\n",
    "    \"Say hello to somebody\"\n",
    "    return f'Hello {to}!'\n",
    "```\n",
    "\n",
    "this will produce the following output:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#|exec_doc\n",
    "#|echo: true\n",
    "def say_hello(to):\n",
    "    \"Say hello to somebody\"\n",
    "    return f'Hello {to}!'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### say_hello\n",
       "\n",
       ">      say_hello (to)\n",
       "\n",
       "Say hello to somebody"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### say_hello\n",
       "\n",
       ">      say_hello (to)\n",
       "\n",
       "Say hello to somebody"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|echo: false\n",
    "show_doc(say_hello)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cell Execution\n",
    "\n",
    "The following directives allow you to control how cells are executed during docs rendering and testing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 📓 `#|exec_doc`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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). \n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "import datetime"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "datetime.datetime(2022, 8, 18, 9, 1, 43, 907609)"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "datetime.datetime.now()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However with the annotation:\n",
    "```python\n",
    "#|exec_doc\n",
    "datetime.datetime.now()\n",
    "```\n",
    "\n",
    "we can see that the time has been updated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "datetime.datetime(2022, 8, 18, 9, 1, 43, 911506)"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|exec_doc\n",
    "datetime.datetime.now()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 🔵 `#|eval: <true|false>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When set to `false`, the cell is ignored during testing.\n",
    "\n",
    "::: {.callout-note collapse=\"true\"}\n",
    "\n",
    "##### Example\n",
    "\n",
    "```python\n",
    "#|eval: false\n",
    "raise Exception(\"I'm not raised because I'm not run\")\n",
    "```\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cell execution when there is no directive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When a cell has no directives, cells are run by nbdev according to the behavior [described here](docs.ipynb#automatic-cell-execution)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "jupytext": {
   "split_at_heading": true
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}