nbconvert.rst
217 lines
| 6.7 KiB
| text/x-rst
|
RstLexer
|
r11835 | .. _nbconvert: | ||
|
r11792 | |||
Converting notebooks to other formats | ||||
===================================== | ||||
Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which | ||||
allows you to convert an ``.ipynb`` notebook document file into various static | ||||
formats. | ||||
Currently, ``nbconvert`` is provided as a command line tool, run as a script | ||||
|
r11824 | using IPython. A direct export capability from within the | ||
|
r11792 | IPython Notebook web app is planned. | ||
The command-line syntax to run the ``nbconvert`` script is:: | ||||
|
r11824 | $ ipython nbconvert --to FORMAT notebook.ipynb | ||
|
r11792 | |||
This will convert the IPython document file ``notebook.ipynb`` into the output | ||||
format given by the ``FORMAT`` string. | ||||
|
r11824 | The default output format is html, for which the ``--to`` argument may be | ||
|
r11792 | omitted:: | ||
$ ipython nbconvert notebook.ipynb | ||||
|
r11824 | IPython provides a few templates for some output formats, and these can be | ||
specified via an additional ``--template`` argument. | ||||
|
r11792 | |||
|
r11824 | The currently supported export formats are: | ||
|
r11792 | |||
|
r11824 | * ``--to html`` | ||
|
r11792 | |||
|
r11824 | - ``--template full`` (default) | ||
|
r11837 | |||
|
r11824 | A full static HTML render of the notebook. | ||
This looks very similar to the interactive view. | ||||
|
r11792 | |||
|
r11824 | - ``--template basic`` | ||
|
r11837 | |||
|
r11824 | Simplified HTML, useful for embedding in webpages, blogs, etc. | ||
This excludes HTML headers. | ||||
|
r11792 | |||
|
r11824 | * ``--to latex`` | ||
|
r11837 | |||
|
r11824 | Latex export. This generates ``NOTEBOOK_NAME.tex`` file, | ||
ready for export. You can automatically run latex on it to generate a PDF | ||||
by adding ``--post PDF``. | ||||
- ``--template article`` (default) | ||||
|
r11837 | |||
|
r11824 | Latex article, derived from Sphinx's howto template. | ||
|
r11792 | |||
|
r11824 | - ``--template book`` | ||
|
r11837 | |||
|
r11824 | Latex book, derived from Sphinx's manual template. | ||
|
r11792 | |||
|
r11824 | - ``--template basic`` | ||
|
r11837 | |||
|
r11824 | Very basic latex output - mainly meant as a starting point for custom templates. | ||
|
r11792 | |||
|
r11824 | * ``--to slides`` | ||
|
r11792 | |||
|
r11824 | This generates a Reveal.js HTML slideshow. | ||
It must be served by an HTTP server. The easiest way to get this is to add | ||||
``--post serve`` on the command-line. | ||||
|
r11894 | If you want to use the speaker notes plugin, just add | ||
|
r12156 | ``--slide-notes=True`` on the command-line. | ||
|
r11895 | For low connectivity environments, you can use a local copy of the reveal.js library, | ||
|
r12156 | just add ``--offline-slides=reveal.js`` on the command-line, and do not forget to move | ||
|
r11960 | your downloaded ``reveal.js`` library to the same folder where your slides are located. | ||
|
r11894 | |||
|
r11837 | * ``--to markdown`` | ||
Simple markdown output. Markdown cells are unaffected, | ||||
|
r12097 | and code cells are placed in triple-backtick (```````) blocks. | ||
|
r11837 | |||
* ``--to rst`` | ||||
|
r11792 | |||
|
r11837 | Basic reStructuredText output. Useful as a starting point for embedding notebooks | ||
in Sphinx docs. | ||||
|
r11792 | |||
|
r11837 | * ``--to python`` | ||
Convert a notebook to an executable Python script. | ||||
|
r11824 | This is the simplest way to get a Python script out of a notebook. | ||
If there were any magics in the notebook, this may only be executable from | ||||
an IPython session. | ||||
|
r11837 | |||
|
r11838 | .. note:: | ||
nbconvert uses pandoc_ to convert between various markup languages, | ||||
so pandoc is a dependency of most nbconvert transforms, | ||||
excluding Markdown and Python. | ||||
.. _pandoc: http://johnmacfarlane.net/pandoc/ | ||||
|
r11792 | |||
|
r11824 | The output file created by ``nbconvert`` will have the same base name as | ||
|
r11792 | the notebook and will be placed in the current working directory. Any | ||
supporting files (graphics, etc) will be placed in a new directory with the | ||||
same base name as the notebook, suffixed with ``_files``:: | ||||
$ ipython nbconvert notebook.ipynb | ||||
$ ls | ||||
notebook.ipynb notebook.html notebook_files/ | ||||
|
r11824 | For simple single-file output, such as html, markdown, etc., | ||
the output may be sent to standard output with:: | ||||
|
r11792 | |||
|
r11824 | $ ipython nbconvert --to markdown notebook.ipynb --stdout | ||
|
r11792 | |||
Multiple notebooks can be specified from the command line:: | ||||
$ ipython nbconvert notebook*.ipynb | ||||
$ ipython nbconvert notebook1.ipynb notebook2.ipynb | ||||
or via a list in a configuration file, say ``mycfg.py``, containing the text:: | ||||
c = get_config() | ||||
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"] | ||||
and using the command:: | ||||
$ ipython nbconvert --config mycfg.py | ||||
.. _notebook_format: | ||||
Notebook JSON file format | ||||
------------------------- | ||||
|
r11824 | |||
|
r11792 | Notebook documents are JSON files with an ``.ipynb`` extension, formatted | ||
as legibly as possible with minimal extra indentation and cell content broken | ||||
across lines to make them reasonably friendly to use in version-control | ||||
workflows. You should be very careful if you ever manually edit this JSON | ||||
data, as it is extremely easy to corrupt its internal structure and make the | ||||
file impossible to load. In general, you should consider the notebook as a | ||||
file meant only to be edited by the IPython Notebook app itself, not for | ||||
hand-editing. | ||||
.. note:: | ||||
Binary data such as figures are also saved directly in the JSON file. | ||||
This provides convenient single-file portability, but means that the | ||||
files can be large; a ``diff`` of binary data is also not very | ||||
meaningful. Since the binary blobs are encoded in a single line, they | ||||
affect only one line of the ``diff`` output, but they are typically very | ||||
long lines. You can use the ``Cell | All Output | Clear`` menu option to | ||||
remove all output from a notebook prior to committing it to version | ||||
control, if this is a concern. | ||||
The notebook server can also generate a pure Python version of your notebook, | ||||
using the ``File | Download as`` menu option. The resulting ``.py`` file will | ||||
contain all the code cells from your notebook verbatim, and all Markdown cells | ||||
prepended with a comment marker. The separation between code and Markdown | ||||
cells is indicated with special comments and there is a header indicating the | ||||
format version. All output is removed when exporting to Python. | ||||
As an example, consider a simple notebook called ``simple.ipynb`` which | ||||
contains one Markdown cell, with the content ``The simplest notebook.``, one | ||||
code input cell with the content ``print "Hello, IPython!"``, and the | ||||
corresponding output. | ||||
The contents of the notebook document ``simple.ipynb`` is the following JSON | ||||
container:: | ||||
{ | ||||
"metadata": { | ||||
"name": "simple" | ||||
}, | ||||
"nbformat": 3, | ||||
"nbformat_minor": 0, | ||||
"worksheets": [ | ||||
{ | ||||
"cells": [ | ||||
{ | ||||
"cell_type": "markdown", | ||||
"metadata": {}, | ||||
"source": "The simplest notebook." | ||||
}, | ||||
{ | ||||
"cell_type": "code", | ||||
"collapsed": false, | ||||
"input": "print \"Hello, IPython\"", | ||||
"language": "python", | ||||
"metadata": {}, | ||||
"outputs": [ | ||||
{ | ||||
"output_type": "stream", | ||||
"stream": "stdout", | ||||
"text": "Hello, IPython\n" | ||||
} | ||||
], | ||||
"prompt_number": 1 | ||||
} | ||||
], | ||||
"metadata": {} | ||||
} | ||||
] | ||||
} | ||||
The corresponding Python script is:: | ||||
# -*- coding: utf-8 -*- | ||||
# <nbformat>3.0</nbformat> | ||||
# <markdowncell> | ||||
# The simplest notebook. | ||||
# <codecell> | ||||
print "Hello, IPython" | ||||
Note that indeed the output of the code cell, which is present in the JSON | ||||
container, has been removed in the ``.py`` script. | ||||