README.rst
124 lines
| 2.8 KiB
| text/x-rst
|
RstLexer
Anton I. Sipos
|
r6242 | ================================================================ | ||
Matthias BUSSONNIER
|
r9802 | nbconvert: conversion utilities for the IPython notebook format | ||
Anton I. Sipos
|
r6242 | ================================================================ | ||
Overview | ||||
======== | ||||
nbconvert provides command line utilities to convert to and from IPython | ||||
Matthias BUSSONNIER
|
r9802 | notebooks and standard formats. | ||
- ReST | ||||
- Markdown | ||||
- HTML | ||||
- Python script | ||||
Matthias BUSSONNIER
|
r9806 | - LaTeX (through Sphinx) | ||
Matthias BUSSONNIER
|
r9802 | |||
As these tools mature, these utilities will be merged into IPython. | ||||
Anton I. Sipos
|
r6242 | |||
Anton I. Sipos
|
r6245 | Requirements | ||
============ | ||||
Fernando Perez
|
r8393 | |||
Matthias BUSSONNIER
|
r9802 | Jinja2 | ||
~~~~~~ | ||||
Kyle Kelley
|
r10062 | Most of the converters should rely on the Jinja2 templating language. | ||
Matthias BUSSONNIER
|
r9802 | |||
Markdown | ||||
~~~~~~~~ | ||||
You will need the `python markdown module | ||||
<http://pypi.python.org/pypi/Markdown>`_ :: | ||||
$ pip install markdown | ||||
Docutils | ||||
~~~~~~~~ | ||||
Kyle Kelley
|
r10062 | nbconvert requires the latest development version of docutils. This can be installed | ||
Matthias BUSSONNIER
|
r9802 | via :: | ||
$ curl http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar > docutils.tgz | ||||
$ pip install -U docutils.tgz | ||||
Sphinx-Latex | ||||
~~~~~~~~~~~~ | ||||
Kyle Kelley
|
r10062 | We are trying to require as little as possible, but for now, compiling the generated Tex file requires texlive-full. | ||
Jonathan Frederic
|
r9755 | :: | ||
Jonathan Frederic
|
r9760 | |||
sudo apt-get install texlive-full | ||||
Jonathan Frederic
|
r9738 | |||
Jonathan Frederic
|
r9752 | See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html | ||
Fernando Perez
|
r8394 | |||
Jonathan Frederic
|
r9758 | |||
Matthias BUSSONNIER
|
r9802 | Testing for Sphinx Latex | ||
~~~~~~~~~~~~~~~~~~~~~~~~ | ||||
Jonathan Frederic
|
r9758 | |||
To test, I place a Test1.ipynb file in my nbconvert directory. | ||||
Jonathan Frederic
|
r9760 | Then I run this shell script | ||
Jonathan Frederic
|
r9758 | |||
:: | ||||
Jonathan Frederic
|
r9760 | |||
Jonathan Frederic
|
r9777 | mkdir Test1_files | ||
rm Test1_files/* | ||||
python nbconvert2.py latex_sphinx_howto Test1.ipynb | ||||
mv Test1.tex Test1_files/Test1.tex | ||||
cd Test1_files | ||||
Jonathan Frederic
|
r9760 | pdflatex Test1.tex | ||
Jonathan Frederic
|
r9758 | |||
Jonathan Frederic
|
r9777 | This script will build a Sphinx-howto out of the Test1 IPython notebook. | ||
Replace "howto" with "manual" to build a manual. | ||||
Matthias BUSSONNIER
|
r9802 | Tested against | ||
Jonathan Frederic
|
r9777 | https://github.com/unpingco/Python-for-Signal-Processing | ||
Matthias BUSSONNIER
|
r9802 | |||
Pandoc | ||||
~~~~~~ | ||||
Nbconvert also needs the `pandoc multiformat converter | ||||
<http://johnmacfarlane.net/pandoc>`_ to do the actual text conversions. Pandoc | ||||
Kyle Kelley
|
r10064 | is included in most Linux distribution's package managers, and the author's | ||
Matthias BUSSONNIER
|
r9802 | website contains links to Mac OS X and Windows installers. | ||
Pandoc, to convert markdown into latex | ||||
:: | ||||
sudo apt-get install pandoc | ||||
Pygment | ||||
~~~~~~~ | ||||
For conversion to HTML/LaTeX, pygments is also required for syntax highlighting | ||||
:: | ||||
$ pip install pygments | ||||
Running Tests | ||||
============= | ||||
MinRK
|
r10181 | Please try to run the tests to avoid regression when committing a patch, and create new tests when adding features. | ||
Matthias BUSSONNIER
|
r9802 | :: | ||
$ pip install nose | ||||
$ nosetests | ||||
Using nbconvert | ||||
=============== | ||||
You will need to either put the source repository in your ``$PATH`` or symlink | ||||
MinRK
|
r10181 | the ``nbconvert2.py`` script to a directory in your ``$PATH``, e.g.:: | ||
Matthias BUSSONNIER
|
r9802 | |||
MinRK
|
r10181 | $ ln -s /usr/local/bin/nbconvert "$PWD/nbconvert2.py" | ||
Once this is done, you can call it as:: | ||||
$ nbconvert <FORMAT> notebook.ipynb > converted.fmt | ||||
Matthias BUSSONNIER
|
r9802 | |||
Use ``nbconvert -h`` for up to date help on the available formats. | ||||