{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# How to Use NBConvert" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### NBconvert migration" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "NBconvert has now been merged into IPython itself. You will need IPython 1.0 or above to have this works (asuuming the API have not changed)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Intro" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this post I will introduce you to the programatic API of nbconvert to show you how to use it in various context. \n", "\n", "For this I will use one of [@jakevdp](https://github.com/jakevdp) great [blog post](http://jakevdp.github.io/blog/2013/04/15/code-golf-in-python-sudoku/).\n", "I've explicitely chosen a post with no javascript tricks as Jake seem to be found of right now, for the reason that the becommings of embeding javascript in nbviewer, which is based on nbconvert is not fully decided yet. \n", "\n", "\n", "This will not focus on using the command line tool to convert file. The attentive reader will point-out that no data are read from, or written to disk during the conversion process. Indeed, nbconvert as been though as much as\n", "possible to avoid IO operation and work as well in a database, or web-based environement." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Quick overview" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The main principle of nbconvert is to instanciate a `Exporter` that controle\n", "a pipeline through which each notebook you want to export with go through.\n", "\n", "Let's start by importing what we need from the API, and download @jakevdp's notebook." ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'{\\n \"metadata\": {\\n \"name\": \"XKCD_plots\"\\n },\\n \"nbformat\": 3,\\n...'" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import requests\n", "response = requests.get('http://jakevdp.github.com/downloads/notebooks/XKCD_plots.ipynb')\n", "response.content[0:60]+'...'" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We read the response into a slightly more convenient format which represent IPython notebook. \n", "There are not real advantages for now, except some convenient methods, but with time this structure should be able to\n", "guarantee that the notebook structure is valid." ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "{u'cell_type': u'heading',\n", " u'level': 1,\n", " u'metadata': {},\n", " u'source': u'XKCD plots in Matplotlib'}" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from IPython.nbformat import current as nbformat\n", "jake_notebook = nbformat.reads_json(response.content)\n", "jake_notebook.worksheets[0].cells[0]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "So we have here Jake's notebook in a convenient for, which is mainly a Super-Powered dict and list nested.\n", "You don't need to worry about the exact structure." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The nbconvert API exposes some basic exporter for common format and default options. We will start\n", "by using one of them. First we import it, instanciate an instance with all the defautl parameters and fed it\n", "the downloaded notebook. " ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import IPython.nbconvert" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false }, "outputs": [], "source": [ "from IPython.config import Config\n", "from IPython.nbconvert import HTMLExporter\n", "\n", "## I use basic here to have less boilerplate and headers in the HTML.\n", "## we'll see later how to pass config to exporters.\n", "exportHtml = HTMLExporter(config=Config({'HTMLExporter':{'default_template':'basic'}}))" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": false }, "outputs": [], "source": [ "(body,resources) = exportHtml.from_notebook_node(jake_notebook)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The exporter returns a tuple containing the body of the converted notebook, here raw HTML, as well as a resources dict.\n", "The resource dict contains (among many things) the extracted PNG, JPG [...etc] from the notebook when applicable.\n", "The basic HTML exporter does keep them as embeded base64 into the notebook, but one can do ask the figures to be extracted. Cf advance use. So for now the resource dict **should** be mostly empty, except for 1 key containing some css, and 2 others whose content will be obvious.\n", "\n", "Exporter are stateless, you won't be able to extract any usefull information (except their configuration) from them.\n", "You can directly re-use the instance to convert another notebook. Each exporter expose for convenience a `from_file` and `from_filename` methods if you need." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "['inlining', 'output_extension', 'metadata']\n", "defaultdict(None, {'name': 'Notebook'})\n", "html\n" ] } ], "source": [ "print resources.keys()\n", "print resources['metadata']\n", "print resources['output_extension']\n", "# print resources['inlining'] # too lng to be shown" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "
This notebook originally appeared as a blog post at `_\n",
"by Jake Vanderplas.\n",
"\n",
" *Update: the matplotlib pull request has been merged! See* `*This\n",
"post* This post was written entirely in an IPython Notebook: the notebook file is available for download here. For more information on blogging with notebooks in octopress, see my previous post on the subject.