{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": false
   },
   "outputs": [],
   "source": [
    "#default_exp nbdev_comments\n",
    "from nbdev.showdoc import show_doc "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# nbdev comments \n",
    "\n",
    "> list of all special comments used in nbdev"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev comments for exporting cells to modules."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #default_exp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `#default_exp module_name` specifies that code exported from this notebook will be placed in the destination \"*module_name.py*\" module.  \n",
    "Use dots `.` for submodules and do not include the `.py` file extension. For example, `#default_exp module.submodule` sets the destination module to \"*module/submodule.py*\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If specific cells need to be exported to a different module, indicate it after #export: `#export special.module`  \n",
    "\n",
    "* 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](http://xion.io/post/code/python-all-wild-imports.html). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #export"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add `#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. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "a cell marked with `#export` will have its signature added to the documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "#export \n",
    "class S1():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export \n",
    "class S1():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #exports"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`#exports` is just like `#export` but will additionally have the source code added to the documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "#exports \n",
    "class S2():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#exports \n",
    "class S2():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #exporti"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add `#exporti` for each cell you want exported without it being added to `__all__`, and without it showing up in the docs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "#exporti\n",
    "class S3():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#exporti\n",
    "class S3():\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hide comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev comments for hiding cells, inputs, or outputs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #hide"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This comment instructs nbdev to hide the cell when generating the docs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "#hide\n",
    "print(\"output\")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "output\n"
     ]
    }
   ],
   "source": [
    "#hide\n",
    "print(\"output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #hide_input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `#hide_input` at the top of a cell if you don't want code to be shown in the docs.  \n",
    "cells containing `#export` or `show_doc` have their code hidden automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is output. Input is hidden using #hide_input\n"
     ]
    }
   ],
   "source": [
    "#hide_input\n",
    "print(\"This is output. Input is hidden using #hide_input\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #hide_output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use `#hide_output` at the top of a cell if you don't want output to be shown in the docs.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is input. Output is hidden using #hide_output\n"
     ]
    }
   ],
   "source": [
    "#hide_output\n",
    "print(\"This is input. Output is hidden using #hide_output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Collapse comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev comments for having inputs or outputs under a collapsable element. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #collapse_input"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "use `#collapse_input` to include code in the docs under a collapsable element. The collapsable element is closed by default."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `#collapse_input open` in a code cell will include your code under a collapsable element that is open by default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "This is output. Input is collapsed using #collapse_input\n"
     ]
    }
   ],
   "source": [
    "#collapse_input\n",
    "print(\"This is output. Input is collapsed using #collapse_input\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #collapse_output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "use `#collapse_output` to include output in the docs under a collapsable element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Output is collapsed using #collapse_output\n"
     ]
    }
   ],
   "source": [
    "#collapse_output\n",
    "print(\"Output is collapsed using #collapse_output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Docs comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### #default_cls_lvl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#default_cls_lvl 4"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "above cell changes the level of classes in this notebook to 4. Check TOC at the top of this page."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Test flags"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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.\n",
    "\n",
    "If `tst_flags=slow|fastai` in *settings.ini*, you can:\n",
    "\n",
    "* mark slow tests with `#slow` flag\n",
    "* mark tests that depend on fastai with the `#fastai` flag."
   ]
  }
 ],
 "metadata": {
  "jekyll": {
   "keywords": "fastai",
   "toc": "false"
  },
  "jupytext": {
   "split_at_heading": true
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}