Show More
@@ -1,261 +1,192 b'' | |||
|
1 | 1 | |
|
2 | 2 | |
|
3 | 3 | .. _`nbconvert script`: |
|
4 | 4 | |
|
5 | 5 | Converting notebooks to other formats |
|
6 | 6 | ===================================== |
|
7 | 7 | |
|
8 | 8 | Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which |
|
9 | 9 | allows you to convert an ``.ipynb`` notebook document file into various static |
|
10 | 10 | formats. |
|
11 | 11 | |
|
12 | 12 | Currently, ``nbconvert`` is provided as a command line tool, run as a script |
|
13 |
using IPython. |
|
|
13 | using IPython. A direct export capability from within the | |
|
14 | 14 | IPython Notebook web app is planned. |
|
15 | 15 | |
|
16 | 16 | The command-line syntax to run the ``nbconvert`` script is:: |
|
17 | 17 | |
|
18 |
$ ipython nbconvert -- |
|
|
18 | $ ipython nbconvert --to FORMAT notebook.ipynb | |
|
19 | 19 | |
|
20 | 20 | This will convert the IPython document file ``notebook.ipynb`` into the output |
|
21 | 21 | format given by the ``FORMAT`` string. |
|
22 | 22 | |
|
23 |
The default output format is |
|
|
23 | The default output format is html, for which the ``--to`` argument may be | |
|
24 | 24 | omitted:: |
|
25 | 25 | |
|
26 | 26 | $ ipython nbconvert notebook.ipynb |
|
27 | 27 | |
|
28 | The currently supported export formats are the following: | |
|
28 | IPython provides a few templates for some output formats, and these can be | |
|
29 | specified via an additional ``--template`` argument. | |
|
29 | 30 | |
|
30 | * HTML: | |
|
31 | The currently supported export formats are: | |
|
31 | 32 | |
|
32 | - **full_html**: | |
|
33 | Standard HTML | |
|
33 | * ``--to html`` | |
|
34 | 34 | |
|
35 | - **simple_html**: | |
|
36 | Simplified HTML | |
|
35 | - ``--template full`` (default) | |
|
36 | A full static HTML render of the notebook. | |
|
37 | This looks very similar to the interactive view. | |
|
37 | 38 | |
|
38 | - **reveal**: | |
|
39 | HTML slideshow presentation for use with the ``reveal.js`` package | |
|
39 | - ``--template basic`` | |
|
40 | Simplified HTML, useful for embedding in webpages, blogs, etc. | |
|
41 | This excludes HTML headers. | |
|
40 | 42 | |
|
41 | * PDF: | |
|
43 | * ``--to latex`` | |
|
44 | Latex export. This generates ``NOTEBOOK_NAME.tex`` file, | |
|
45 | ready for export. You can automatically run latex on it to generate a PDF | |
|
46 | by adding ``--post PDF``. | |
|
42 | 47 | |
|
43 | - **sphinx_howto**: | |
|
44 | The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX | |
|
48 | - ``--template article`` (default) | |
|
49 | Latex article, derived from Sphinx's howto template. | |
|
45 | 50 | |
|
46 | - **sphinx_manual**: | |
|
47 | The format for Sphinx_ manuals; similar to a ``book`` in LaTeX | |
|
51 | - ``--template book`` | |
|
52 | Latex book, derived from Sphinx's manual template. | |
|
48 | 53 | |
|
49 | - **latex**: | |
|
50 | An article formatted completely using LaTeX | |
|
54 | - ``--template basic`` | |
|
55 | Very basic latex output - mainly meant as a starting point for custom templates. | |
|
51 | 56 | |
|
52 | * Markup: | |
|
57 | * ``--to slides`` | |
|
53 | 58 | |
|
54 | - **rst**: | |
|
55 | reStructuredText_ markup | |
|
59 | This generates a Reveal.js HTML slideshow. | |
|
60 | It must be served by an HTTP server. The easiest way to get this is to add | |
|
61 | ``--post serve`` on the command-line. | |
|
56 | 62 | |
|
57 | - **markdown**: | |
|
58 | Markdown_ markup | |
|
63 | * ``--to markdown`` Simple markdown | |
|
59 | 64 | |
|
60 | .. _Sphinx: http://sphinx-doc.org/ | |
|
61 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
|
62 | .. _Markdown: http://daringfireball.net/projects/markdown/syntax | |
|
65 | * ``--to rst`` reStructuredText | |
|
63 | 66 | |
|
64 | * Python: | |
|
67 | * ``--to python`` Convert a notebook to an executable Python script. | |
|
68 | This is the simplest way to get a Python script out of a notebook. | |
|
69 | If there were any magics in the notebook, this may only be executable from | |
|
70 | an IPython session. | |
|
65 | 71 | |
|
66 | Comments out all the non-Python code to produce a ``.py`` Python | |
|
67 | script with just the code content. Currently the output includes IPython | |
|
68 | magics, and so can be run with ``ipython``, after changing the extension | |
|
69 | of the script to ``.ipy``. | |
|
70 | ||
|
71 | The files output file created by ``nbconvert`` will have the same base name as | |
|
72 | The output file created by ``nbconvert`` will have the same base name as | |
|
72 | 73 | the notebook and will be placed in the current working directory. Any |
|
73 | 74 | supporting files (graphics, etc) will be placed in a new directory with the |
|
74 | 75 | same base name as the notebook, suffixed with ``_files``:: |
|
75 | 76 | |
|
76 | 77 | $ ipython nbconvert notebook.ipynb |
|
77 | 78 | $ ls |
|
78 | 79 | notebook.ipynb notebook.html notebook_files/ |
|
79 | 80 | |
|
80 | Each of the options for PDF export produces as an intermediate step a LaTeX | |
|
81 | ``.tex`` file with the same basename as the notebook, as well as individual | |
|
82 | files for each figure, and ``.text`` files with textual output from running | |
|
83 | code cells. | |
|
84 | ||
|
85 | To actually produce the final PDF file, run the following commands:: | |
|
86 | ||
|
87 | $ ipython nbconvert --format=latex notebook.ipynb | |
|
88 | $ pdflatex notebook | |
|
81 | For simple single-file output, such as html, markdown, etc., | |
|
82 | the output may be sent to standard output with:: | |
|
89 | 83 | |
|
90 | This requires a local installation of LaTeX on your machine. | |
|
91 | The output is a PDF file ``notebook.pdf``, also placed inside the | |
|
92 | ``nbconvert_build`` subdirectory. | |
|
93 | ||
|
94 | Alternatively, the output may be sent to standard output with:: | |
|
95 | ||
|
96 | $ ipython nbconvert notebook.ipynb --stdout | |
|
84 | $ ipython nbconvert --to markdown notebook.ipynb --stdout | |
|
97 | 85 | |
|
98 | 86 | Multiple notebooks can be specified from the command line:: |
|
99 | 87 | |
|
100 | 88 | $ ipython nbconvert notebook*.ipynb |
|
101 | 89 | $ ipython nbconvert notebook1.ipynb notebook2.ipynb |
|
102 | 90 | |
|
103 | 91 | or via a list in a configuration file, say ``mycfg.py``, containing the text:: |
|
104 | 92 | |
|
105 | 93 | c = get_config() |
|
106 | 94 | c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"] |
|
107 | 95 | |
|
108 | 96 | and using the command:: |
|
109 | 97 | |
|
110 | 98 | $ ipython nbconvert --config mycfg.py |
|
111 | 99 | |
|
112 | 100 | |
|
113 | Extracting standard Python files from notebooks | |
|
114 | ----------------------------------------------- | |
|
115 | ``.ipynb`` notebook document files are plain text files which store a | |
|
116 | representation in JSON format of the contents of a notebook space. As such, | |
|
117 | they are not valid ``.py`` Python scripts, and so can be neither imported | |
|
118 | directly with ``import`` in Python, nor run directly as a standard Python | |
|
119 | script (though both of these are possible with simple workarounds). | |
|
120 | ||
|
121 | ||
|
122 | To extract the Python code from within a notebook document, the simplest | |
|
123 | method is to use the ``File | Download as | Python (.py)`` menu item; the | |
|
124 | resulting ``.py`` script will be downloaded to your browser's default | |
|
125 | download location. | |
|
126 | ||
|
127 | An alternative is to pass an argument to the IPython Notebook, from the moment | |
|
128 | when it is originally started, specifying that whenever it saves an ``.ipynb`` | |
|
129 | notebook document, it should, at the same time, save the corresponding | |
|
130 | ``.py`` script. To do so, you can execute the following command:: | |
|
131 | ||
|
132 | $ ipython notebook --script | |
|
133 | ||
|
134 | or you can set this option permanently in your configuration file with:: | |
|
135 | ||
|
136 | c = get_config() | |
|
137 | c.NotebookManager.save_script=True | |
|
138 | ||
|
139 | The result is that standard ``.py`` files are also now generated, which | |
|
140 | can be ``%run``, imported from regular IPython sessions or other notebooks, or | |
|
141 | executed at the command line, as usual. Since the raw code you have typed is | |
|
142 | exported, you must avoid using syntax such as IPython magics and other | |
|
143 | IPython-specific extensions to the language for the files to be able to be | |
|
144 | successfully imported. | |
|
145 | .. or you can change the script's extension to ``.ipy`` and run it with:: | |
|
146 | .. | |
|
147 | .. $ ipython script.ipy | |
|
148 | ||
|
149 | In normal Python practice, the standard way to differentiate importable code | |
|
150 | in a Python script from the "executable" part of a script is to use the | |
|
151 | following idiom at the start of the executable part of the code:: | |
|
152 | ||
|
153 | if __name__ == '__main__' | |
|
154 | ||
|
155 | # rest of the code... | |
|
156 | ||
|
157 | Since all cells in the notebook are run as top-level code, you will need to | |
|
158 | similarly protect *all* cells that you do not want executed when other scripts | |
|
159 | try to import your notebook. A convenient shortand for this is to define | |
|
160 | early on:: | |
|
161 | ||
|
162 | script = __name__ == '__main__' | |
|
163 | ||
|
164 | Then in any cell that you need to protect, use:: | |
|
165 | ||
|
166 | if script: | |
|
167 | # rest of the cell... | |
|
168 | ||
|
169 | ||
|
170 | ||
|
171 | 101 | .. _notebook_format: |
|
172 | 102 | |
|
173 | 103 | Notebook JSON file format |
|
174 | 104 | ------------------------- |
|
105 | ||
|
175 | 106 | Notebook documents are JSON files with an ``.ipynb`` extension, formatted |
|
176 | 107 | as legibly as possible with minimal extra indentation and cell content broken |
|
177 | 108 | across lines to make them reasonably friendly to use in version-control |
|
178 | 109 | workflows. You should be very careful if you ever manually edit this JSON |
|
179 | 110 | data, as it is extremely easy to corrupt its internal structure and make the |
|
180 | 111 | file impossible to load. In general, you should consider the notebook as a |
|
181 | 112 | file meant only to be edited by the IPython Notebook app itself, not for |
|
182 | 113 | hand-editing. |
|
183 | 114 | |
|
184 | 115 | .. note:: |
|
185 | 116 | |
|
186 | 117 | Binary data such as figures are also saved directly in the JSON file. |
|
187 | 118 | This provides convenient single-file portability, but means that the |
|
188 | 119 | files can be large; a ``diff`` of binary data is also not very |
|
189 | 120 | meaningful. Since the binary blobs are encoded in a single line, they |
|
190 | 121 | affect only one line of the ``diff`` output, but they are typically very |
|
191 | 122 | long lines. You can use the ``Cell | All Output | Clear`` menu option to |
|
192 | 123 | remove all output from a notebook prior to committing it to version |
|
193 | 124 | control, if this is a concern. |
|
194 | 125 | |
|
195 | 126 | The notebook server can also generate a pure Python version of your notebook, |
|
196 | 127 | using the ``File | Download as`` menu option. The resulting ``.py`` file will |
|
197 | 128 | contain all the code cells from your notebook verbatim, and all Markdown cells |
|
198 | 129 | prepended with a comment marker. The separation between code and Markdown |
|
199 | 130 | cells is indicated with special comments and there is a header indicating the |
|
200 | 131 | format version. All output is removed when exporting to Python. |
|
201 | 132 | |
|
202 | 133 | As an example, consider a simple notebook called ``simple.ipynb`` which |
|
203 | 134 | contains one Markdown cell, with the content ``The simplest notebook.``, one |
|
204 | 135 | code input cell with the content ``print "Hello, IPython!"``, and the |
|
205 | 136 | corresponding output. |
|
206 | 137 | |
|
207 | 138 | The contents of the notebook document ``simple.ipynb`` is the following JSON |
|
208 | 139 | container:: |
|
209 | 140 | |
|
210 | 141 | { |
|
211 | 142 | "metadata": { |
|
212 | 143 | "name": "simple" |
|
213 | 144 | }, |
|
214 | 145 | "nbformat": 3, |
|
215 | 146 | "nbformat_minor": 0, |
|
216 | 147 | "worksheets": [ |
|
217 | 148 | { |
|
218 | 149 | "cells": [ |
|
219 | 150 | { |
|
220 | 151 | "cell_type": "markdown", |
|
221 | 152 | "metadata": {}, |
|
222 | 153 | "source": "The simplest notebook." |
|
223 | 154 | }, |
|
224 | 155 | { |
|
225 | 156 | "cell_type": "code", |
|
226 | 157 | "collapsed": false, |
|
227 | 158 | "input": "print \"Hello, IPython\"", |
|
228 | 159 | "language": "python", |
|
229 | 160 | "metadata": {}, |
|
230 | 161 | "outputs": [ |
|
231 | 162 | { |
|
232 | 163 | "output_type": "stream", |
|
233 | 164 | "stream": "stdout", |
|
234 | 165 | "text": "Hello, IPython\n" |
|
235 | 166 | } |
|
236 | 167 | ], |
|
237 | 168 | "prompt_number": 1 |
|
238 | 169 | } |
|
239 | 170 | ], |
|
240 | 171 | "metadata": {} |
|
241 | 172 | } |
|
242 | 173 | ] |
|
243 | 174 | } |
|
244 | 175 | |
|
245 | 176 | |
|
246 | 177 | The corresponding Python script is:: |
|
247 | 178 | |
|
248 | 179 | # -*- coding: utf-8 -*- |
|
249 | 180 | # <nbformat>3.0</nbformat> |
|
250 | 181 | |
|
251 | 182 | # <markdowncell> |
|
252 | 183 | |
|
253 | 184 | # The simplest notebook. |
|
254 | 185 | |
|
255 | 186 | # <codecell> |
|
256 | 187 | |
|
257 | 188 | print "Hello, IPython" |
|
258 | 189 | |
|
259 | 190 | Note that indeed the output of the code cell, which is present in the JSON |
|
260 | 191 | container, has been removed in the ``.py`` script. |
|
261 | 192 |
General Comments 0
You need to be logged in to leave comments.
Login now