README.rst
108 lines
| 2.3 KiB
| text/x-rst
|
RstLexer
Anton I. Sipos
|
r6242 | ================================================================ | ||
Jonathan Frederic
|
r10773 | NbConvert: Conversion utilities for the IPython notebook format | ||
Anton I. Sipos
|
r6242 | ================================================================ | ||
Jonathan Frederic
|
r10773 | |||
Anton I. Sipos
|
r6242 | |||
Overview | ||||
======== | ||||
Jonathan Frederic
|
r10773 | NbConvert provides a command line interface to convert to and from IPython | ||
Matthias BUSSONNIER
|
r9802 | notebooks and standard formats. | ||
Jonathan Frederic
|
r10773 | - ReST | ||
- Markdown | ||||
- HTML | ||||
- Python script | ||||
- Reveal | ||||
- LaTeX | ||||
- Sphinx | ||||
Matthias BUSSONNIER
|
r9802 | |||
Jonathan Frederic
|
r10773 | As these functions mature, they will be merged into IPython. | ||
Anton I. Sipos
|
r6242 | |||
Anton I. Sipos
|
r6245 | Requirements | ||
============ | ||||
Fernando Perez
|
r8393 | |||
Matthias BUSSONNIER
|
r9802 | Jinja2 | ||
~~~~~~ | ||||
Jonathan Frederic
|
r10773 | All of the exporters 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 | ||||
Jonathan Frederic
|
r10773 | |||
Matthias BUSSONNIER
|
r9802 | |||
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 | ||||
Jonathan Frederic
|
r10773 | |||
Matthias BUSSONNIER
|
r9802 | |||
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
|
r10773 | *See http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html for more information* | ||
Matthias BUSSONNIER
|
r9802 | |||
Jonathan Frederic
|
r10773 | |||
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 | ||||
Jonathan Frederic
|
r10773 | |||
Matthias BUSSONNIER
|
r9802 | |||
Pygment | ||||
~~~~~~~ | ||||
For conversion to HTML/LaTeX, pygments is also required for syntax highlighting | ||||
:: | ||||
$ pip install pygments | ||||
Jonathan Frederic
|
r10773 | |||
Matthias BUSSONNIER
|
r9802 | Running Tests | ||
Jonathan Frederic
|
r10773 | ============= | ||
Matthias BUSSONNIER
|
r9802 | |||
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 | ||||
Jonathan Frederic
|
r10773 | |||
Matthias BUSSONNIER
|
r9802 | Using nbconvert | ||
Jonathan Frederic
|
r10773 | =============== | ||
Matthias BUSSONNIER
|
r9802 | |||
You will need to either put the source repository in your ``$PATH`` or symlink | ||||
Jonathan Frederic
|
r10773 | the ``nbconvert.py`` script to a directory in your ``$PATH``, e.g.:: | ||
Matthias BUSSONNIER
|
r9802 | |||
Jonathan Frederic
|
r10773 | $ ln -s /usr/local/bin/nbconvert "$PWD/nbconvert.py" | ||
MinRK
|
r10181 | |||
Once this is done, you can call it as:: | ||||
Jonathan Frederic
|
r10773 | $ nbconvert <FORMAT> notebook.ipynb | ||
Matthias BUSSONNIER
|
r9802 | |||
Use ``nbconvert -h`` for up to date help on the available formats. | ||||