etc/notebooks/associations_demo/associations_demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Local File Associations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook demonstrates two syntaxes for associating local resources (e.g., data files, images) with a notebook. With the `jupyter_cms` extension installed, you can download the notebook and its associated files in a zip. Other extensions, such as `jupyter_dashboards_bundlers`, also take advantage of this feature to bundle files for download or deployment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Syntax 1: Hidden Comment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "urth": {
     "dashboard": {
      "layout": {
       "col": 0,
       "height": 4,
       "row": 0,
       "width": 4
      }
     }
    }
   },
   "source": [
    "To demonstrate the basic feature, let's first load a local CSV file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "urth": {
     "dashboard": {
      "layout": {
       "col": 5,
       "height": 4,
       "row": 0,
       "width": 4
      }
     }
    }
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "cars = pd.read_csv('data/cars.csv')\n",
    "cars"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's imagine we want to send this notebook and the CSV file together to another Jupyter Notebook user. We can use the first association syntax, a Markdown/HTML comment, to associate the CSV file with the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--associate:\n",
    "# The comment must be at the very beginning of a cell, by itself, starting with 'associate:'. Since it is not meant to appear in the output when run, the assumption is that it can require a cell to itself. This example just refers to a single directory, relative to the notebook.\n",
    "data/\n",
    "-->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since this syntax is based on a comment, it is not visible in the rendered notebook document. You must switch a cell to edit mode to see the comment. If you're reading this tutorial in a Jupyter Notebook server, you can double-click the next blank cell right above this one to see the markup. If you're not, here's the hidden markup reproduced as a code block for your convenience:\n",
    "\n",
    "```\n",
    "<!--associate:\n",
    "# The comment must be at the very beginning of a cell, by itself, starting with 'associate:'. Since it is not meant to appear in the output when run, the assumption is that it can require a cell to itself. This example just refers to a single directory, relative to the notebook.\n",
    "data/\n",
    "-->\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, associated filespecs are stated line-by-line according to the same rules used by git (https://git-scm.com/docs/gitignore), with two differences:\n",
    "\n",
    "1. The filespecs represent files to *include*, not *exclude* as in `.gitignore`.\n",
    "2. The filespecs are restricted to paths relative to and rooted at the notebook. Absolute paths and ancestor references (e.g., `../`) are disallowed (and not useful) for portability reasons."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Syntax 2: Fenced Code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's include a reference to a local image using the second supported syntax, one that makes the reference visible in the notebook at all times.\n",
    "\n",
    "Here's the image:\n",
    "\n",
    "![clap](images/MjeLFmy6Lx8di.gif)\n",
    "\n",
    "And here's the reference expressed as a fenced code block in Markdown:\n",
    "\n",
    "```\n",
    "# Comments are still allowed. Of course, there can be more than one filespec here too.\n",
    "images/*.gif\n",
    "```\n",
    "\n",
    "Unlike the comment syntax, this syntax doesn't require a cell for itself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Bundle It!\n",
    "\n",
    "With the two file lists above in place, you can now download your notebook and the associated files all together. Click *File &rarr; Download As &rarr; IPython Notebook bundle (.zip)*. The resulting zip retains the directory structure of your workspace here in Jupyter relative to the notebook file."
   ]
  }
 ],
 "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.4.3"
  },
  "urth": {
   "dashboard": {
    "cellMargin": 10,
    "defaultCellHeight": 20,
    "maxColumns": 12
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}