nbconvert provides command line utilities to convert to and from IPython notebooks and standard formats.

• ReST
• Markdown
• HTML
• Python script
• LaTeX (through Sphinx)

As these tools mature, these utilities will be merged into IPython.

Most of the converters should rely on the Jinja2 templating language.

You will need the python markdown module :

$ pip install markdown

nbconvert requires the latest development version of docutils. This can be installed via :

$ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz
$ pip install -U docutils.tgz

We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full. :

sudo apt-get install texlive-full

See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html

To test, I place a Test1.ipynb file in my nbconvert directory. Then I run this shell script

mkdir Test1_files
rm Test1_files/*

python nbconvert2.py latex_sphinx_howto Test1.ipynb
mv Test1.tex Test1_files/Test1.tex
cd Test1_files
pdflatex Test1.tex

This script will build a Sphinx-howto out of the Test1 IPython notebook. Replace "howto" with "manual" to build a manual.

Tested against https://github.com/unpingco/Python-for-Signal-Processing

Nbconvert also needs the pandoc multiformat converter to do the actual text conversions. Pandoc is included in most Linux distribution's package managers, and the author's website contains links to Mac OS X and Windows installers.

Pandoc, to convert markdown into latex :

sudo apt-get install pandoc

For conversion to HTML/LaTeX, pygments is also required for syntax highlighting :

$ pip install pygments

Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features. :

$ pip install nose
$ nosetests

You will need to either put the source repository in your $PATH or symlink the nbconvert2.py script to a directory in your $PATH, e.g.:

$ ln -s "$PWD/nbconvert2.py" /usr/local/bin/nbconvert

Once this is done, you can call it as:

$ nbconvert <FORMAT> notebook.ipynb > converted.fmt

Use nbconvert -h for up to date help on the available formats.