{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Margo keyword Reference\n",
    "\n",
    "Throughout these notebooks you will notice special comments that start with `# ::`, called Margo notes. These are what we call \"margin notes,\" written using the Margo syntax. They provide extra information to applications that are reading and processing Jupyter Notebook files.\n",
    "\n",
    "Most of the notes used in these notebooks are designed to tell `margo_loader` how to handle each cell when importing a notebook.\n",
    "\n",
    "This reference describes the meaning of each Margo note. To learn how you can make up your own Margo notes for use with `margo-tool` or your own custom applications, read the `Margo Syntax Primer.ipynb` notebook in this repo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## :: ignore-cell ::\n",
    "\n",
    "When the notebook is imported, any cell with `ignore-cell` will be ignored.\n",
    "\n",
    "#### Aliases\n",
    "`# :: skip ::`\n",
    "\n",
    "--------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## :: module-stop ::\n",
    "When the notebook is being imported, this cell and any subsequent cell will be ignored until a `# :: module-start ::` is encountered or the end of the notebook is reached.\n",
    "\n",
    "#### Aliases \n",
    "`# :: stop ::`\n",
    "\n",
    "-------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## :: module-start ::\n",
    "When the notebook is being imported, this cell and any subsequent cell will be included until a `# :: module-stop ::` is encountered or the end of the notebook is reached. This is not necessary before a `# :: module-start ::` because all cells are included by default.\n",
    "\n",
    "#### Aliases \n",
    "`# :: start ::`\n",
    "\n",
    "-------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## :: not-a-notebook ::\n",
    "\n",
    "This notebook is not meant to be imported. If you try to import it, an Exception will be raised.\n",
    "\n",
    "### Aliases\n",
    "\n",
    "`# :: do-not-import ::`\n",
    "\n",
    "-----\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## :: requirements.txt[raw]: '...' ::\n",
    "\n",
    "All of the above Margo notes are Margo *directives*. That is, the have a name, but not associated value. This note is different; it's a Margo *assignment*. It associates a name with a value.\n",
    "\n",
    "This one is used to define a notebook's dependencies in `requirements.txt` format. The CLI tool `margo-tool` is used to extract these values from each notebook and generate a single `requirements.txt` file for the entire repository.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next lesson\n",
    "\n",
    "The keywords described in this chapter are not part of the core Margo syntax. They're only meaningful to the applications that interpret them. In the next lesson we'll learn about the Margo syntax, which is very minimal.\n",
    "\n",
    "Check out [Margo syntax primer.ipynb](./Margo%20syntax%20primer.ipynb)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}