{ "metadata": { "name": "06-NBconvert-Doc-Draft" }, "nbformat": 3, "nbformat_minor": 0, "worksheets": [ { "cells": [ { "cell_type": "heading", "level": 1, "metadata": {}, "source": [ "How to Use NBConvert" ] }, { "cell_type": "heading", "level": 2, "metadata": {}, "source": [ "Warning" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This might have been redacted with a slighly modified version of nbconvert to fix a few bug and reflect more what shoudl happend than what is happening with current nbconvert." ] }, { "cell_type": "heading", "level": 4, "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": "heading", "level": 4, "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", "collapsed": false, "input": [ "import requests\n", "response = requests.get('http://jakevdp.github.com/downloads/notebooks/XKCD_plots.ipynb')\n", "response.content[0:60]+'...'" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 2, "text": [ "'{\\n \"metadata\": {\\n \"name\": \"XKCD_plots\"\\n },\\n \"nbformat\": 3,\\n...'" ] } ], "prompt_number": 2 }, { "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", "collapsed": false, "input": [ "from IPython.nbformat import current as nbformat\n", "jake_notebook = nbformat.reads_json(response.content)\n", "jake_notebook.worksheets[0].cells[0]" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 3, "text": [ "{u'cell_type': u'heading',\n", " u'level': 1,\n", " u'metadata': {},\n", " u'source': u'XKCD plots in Matplotlib'}" ] } ], "prompt_number": 3 }, { "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": "code", "collapsed": false, "input": [ "cd ~/nbconvert/" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "/Users/bussonniermatthias/nbconvert\n" ] } ], "prompt_number": 4 }, { "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", "collapsed": false, "input": [ "import nbconvert\n", "from nbconvert import BasicHtmlExporter\n", "\n", "exportHtml = BasicHtmlExporter()" ], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 5 }, { "cell_type": "code", "collapsed": false, "input": [ "(body,resources) = exportHtml.from_notebook_node(jake_notebook)" ], "language": "python", "metadata": {}, "outputs": [], "prompt_number": 6 }, { "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.\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", "collapsed": false, "input": [ "resources.keys()" ], "language": "python", "metadata": {}, "outputs": [ { "metadata": {}, "output_type": "pyout", "prompt_number": 7, "text": [ "['inlining']" ] } ], "prompt_number": 7 }, { "cell_type": "code", "collapsed": false, "input": [ "# Part of the body, here the first Heading\n", "print body[:200]+'...'" ], "language": "python", "metadata": {}, "outputs": [ { "output_type": "stream", "stream": "stdout", "text": [ "\n", "