examples/Notebook/Converting Notebooks With nbconvert.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# NbConvert"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Command line usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`NbConvert` is both a library and command line tool that allows you to convert notebooks to other formats.  It ships with many common formats: `html`, `latex`, `markdown`, `python`, `rst`, and  `slides`\n",
    "NbConvert relys on the Jinja templating engine, so implementing a new format or tweeking an existing one is easy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can invoke nbconvert by running\n",
    "\n",
    "```bash\n",
    "$ ipython nbconvert <options and arguments>\n",
    "```\n",
    "\n",
    "Call `ipython nbconvert` with the `--help` flag or without any aruments to display the basic help.  For detailed configuration help, use the `--help-all` flag."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic export"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a test, the `Index.ipynb` notebook in the directory will be convert. \n",
    "\n",
    "If you're converting a notebook with code in it, make sure to run the code cells that you're interested in before attempting to convert the notebook.  Unless explicitly requested, nbconvert **does not execute the code cells** of the notebooks that it converts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "ipython nbconvert  'Index.ipynb'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Html is the (configurable) default value.  The verbose form of the same command as above is "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "ipython nbconvert  --to=html 'Index.ipynb'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also convert to latex, which will extract the embeded images.  If the embeded images are SVGs, inkscape is used to convert them to pdf:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "ipython nbconvert  --to=latex 'Index.ipynb'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the latex conversion creates latex, not a PDF.  To create a PDF you need the required third party packages to compile the latex.\n",
    "\n",
    "A `--post` flag is provided for convinience which allows you to have nbconvert automatically compile a PDF for you from your output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "ipython nbconvert  --to=latex 'Index.ipynb' --post=pdf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom templates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Look at the first 20 lines of the `python` exporter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout\n",
    "for l in pyfile[20:40]:\n",
    "    print l"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the code, you can see that non-code cells are also exported.  If you want to change this behavior, you can use a custom template.  The custom template inherits from the Python template and overwrites the markdown blocks so that they are empty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%writefile simplepython.tpl\n",
    "{% extends 'python.tpl'%}\n",
    "\n",
    "{% block markdowncell -%}\n",
    "{% endblock markdowncell %}\n",
    "\n",
    "## we also want to get rig of header cell\n",
    "{% block headingcell -%}\n",
    "{% endblock headingcell %}\n",
    "\n",
    "## and let's change the appearance of input prompt\n",
    "{% block in_prompt %}\n",
    "# This was input cell with prompt number : {{ cell.prompt_number if cell.prompt_number else ' ' }}\n",
    "{%- endblock in_prompt %}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout --template=simplepython.tpl\n",
    "\n",
    "for l in pyfile[4:40]:\n",
    "    print l\n",
    "print '...'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For details about the template syntax, refer to [Jinja's manual](http://jinja2.readthedocs.org/en/latest/intro.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Template that use cells metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The notebook file format supports attaching arbitrary JSON metadata to each cell.  Here, as an exercise, you will use the metadata to tags cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First you need to choose another notebook you want to convert to html, and tag some of the cells with metadata.  You can refere to the file `soln/celldiff.js` as an example or follow the Javascript tutorial to figure out how do change cell metadata.  Assuming you have a notebook with some of the cells tagged as `Easy`|`Medium`|`Hard`|`<None>`, the notebook can be converted specially using a custom template.  Design your template in the cells provided below.\n",
    "\n",
    "The following, unorganized lines of code, may be of help:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "{% extends 'html_full.tpl'%}\n",
    "{% block any_cell %}\n",
    "{{ super() }}\n",
    "<div style=\"background-color:red\">\n",
    "<div style='background-color:orange'>\n",
    "```\n",
    "\n",
    "If your key name under `cell.metadata.example.difficulty`, the following code would get the value of it:\n",
    "\n",
    "`cell['metadata'].get('example',{}).get('difficulty','')`\n",
    "\n",
    "Tip: Use `%%writefile` to edit the template in the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "# ipython nbconvert --to html <your chosen notebook.ipynb> --template=<your template file>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%loadpy soln/coloreddiff.tpl"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# ipython nbconvert --to html '04 - Custom Display Logic.ipynb' --template=soln/coloreddiff.tpl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get rid of all command line flags."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "IPython nbconvert can be configured using the default profile or a profile specified via the `--profile` flag.  Additionally, if a `config.py` file exist in current working directory, nbconvert will use that as config."
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}