Show More
@@ -1,169 +1,168 | |||
|
1 | 1 | .. _nbconvert: |
|
2 | 2 | |
|
3 | 3 | Converting notebooks to other formats |
|
4 | 4 | ===================================== |
|
5 | 5 | |
|
6 | 6 | Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which |
|
7 | 7 | allows you to convert an ``.ipynb`` notebook document file into various static |
|
8 | 8 | formats. |
|
9 | 9 | |
|
10 | 10 | Currently, ``nbconvert`` is provided as a command line tool, run as a script |
|
11 | 11 | using IPython. A direct export capability from within the |
|
12 | 12 | IPython Notebook web app is planned. |
|
13 | 13 | |
|
14 | 14 | The command-line syntax to run the ``nbconvert`` script is:: |
|
15 | 15 | |
|
16 | 16 | $ ipython nbconvert --to FORMAT notebook.ipynb |
|
17 | 17 | |
|
18 | 18 | This will convert the IPython document file ``notebook.ipynb`` into the output |
|
19 | 19 | format given by the ``FORMAT`` string. |
|
20 | 20 | |
|
21 | 21 | The default output format is html, for which the ``--to`` argument may be |
|
22 | 22 | omitted:: |
|
23 | 23 | |
|
24 | 24 | $ ipython nbconvert notebook.ipynb |
|
25 | 25 | |
|
26 | 26 | IPython provides a few templates for some output formats, and these can be |
|
27 | 27 | specified via an additional ``--template`` argument. |
|
28 | 28 | |
|
29 | 29 | The currently supported export formats are: |
|
30 | 30 | |
|
31 | 31 | * ``--to html`` |
|
32 | 32 | |
|
33 | 33 | - ``--template full`` (default) |
|
34 | 34 | |
|
35 | 35 | A full static HTML render of the notebook. |
|
36 | 36 | This looks very similar to the interactive view. |
|
37 | 37 | |
|
38 | 38 | - ``--template basic`` |
|
39 | 39 | |
|
40 | 40 | Simplified HTML, useful for embedding in webpages, blogs, etc. |
|
41 | 41 | This excludes HTML headers. |
|
42 | 42 | |
|
43 | 43 | * ``--to latex`` |
|
44 | 44 | |
|
45 | 45 | Latex export. This generates ``NOTEBOOK_NAME.tex`` file, |
|
46 | 46 | ready for export. |
|
47 | 47 | |
|
48 | 48 | - ``--template article`` (default) |
|
49 | 49 | |
|
50 | 50 | Latex article, derived from Sphinx's howto template. |
|
51 | 51 | |
|
52 | 52 | - ``--template report`` |
|
53 | 53 | |
|
54 | 54 | Latex report, providing a table of contents and chapters. |
|
55 | 55 | |
|
56 | 56 | - ``--template basic`` |
|
57 | 57 | |
|
58 | 58 | Very basic latex output - mainly meant as a starting point for custom templates. |
|
59 | 59 | |
|
60 | 60 | * ``--to pdf`` |
|
61 | 61 | |
|
62 |
Generates a PDF via latex. |
|
|
63 | Supports the same templates as ``--to latex``. | |
|
62 | Generates a PDF via latex. Supports the same templates as ``--to latex``. | |
|
64 | 63 | |
|
65 | 64 | * ``--to slides`` |
|
66 | 65 | |
|
67 | 66 | This generates a Reveal.js HTML slideshow. |
|
68 | 67 | It must be served by an HTTP server. The easiest way to do this is adding |
|
69 | 68 | ``--post serve`` on the command-line. The ``serve`` post-processor proxies |
|
70 | 69 | Reveal.js requests to a CDN if no local Reveal.js library is present. |
|
71 | 70 | To make slides that don't require an internet connection, just place the |
|
72 | 71 | Reveal.js library in the same directory where your_talk.slides.html is located, |
|
73 | 72 | or point to another directory using the ``--reveal-prefix`` alias. |
|
74 | 73 | |
|
75 | 74 | * ``--to markdown`` |
|
76 | 75 | |
|
77 | 76 | Simple markdown output. Markdown cells are unaffected, |
|
78 | 77 | and code cells indented 4 spaces. |
|
79 | 78 | |
|
80 | 79 | * ``--to rst`` |
|
81 | 80 | |
|
82 | 81 | Basic reStructuredText output. Useful as a starting point for embedding notebooks |
|
83 | 82 | in Sphinx docs. |
|
84 | 83 | |
|
85 | 84 | * ``--to script`` |
|
86 | 85 | |
|
87 | 86 | Convert a notebook to an executable script. |
|
88 | 87 | This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook. |
|
89 | 88 | If there were any magics in an IPython notebook, this may only be executable from |
|
90 | 89 | an IPython session. |
|
91 | 90 | |
|
92 | 91 | * ``--to notebook`` |
|
93 | 92 | |
|
94 | 93 | .. versionadded:: 3.0 |
|
95 | 94 | |
|
96 | 95 | This doesn't convert a notebook to a different format *per se*, |
|
97 | 96 | instead it allows the running of nbconvert preprocessors on a notebook, |
|
98 | 97 | and/or conversion to other notebook formats. For example:: |
|
99 | 98 | |
|
100 | 99 | ipython nbconvert --to notebook --execute mynotebook.ipynb |
|
101 | 100 | |
|
102 | 101 | will open the notebook, execute it, capture new output, and save the result in |
|
103 | 102 | :file:`mynotebook.nbconvert.ipynb`. |
|
104 | 103 | |
|
105 | 104 | :: |
|
106 | 105 | |
|
107 | 106 | ipython nbconvert --to notebook --nbformat 3 mynotebook |
|
108 | 107 | |
|
109 | 108 | will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb` |
|
110 | 109 | in version 3 of the :ref:`notebook format <nbformat>`. |
|
111 | 110 | |
|
112 | 111 | If you want to convert a notebook in-place, |
|
113 | 112 | you can specify the ouptut file to be the same as the input file:: |
|
114 | 113 | |
|
115 | 114 | ipython nbconvert --to notebook mynb --output mynb |
|
116 | 115 | |
|
117 | 116 | Be careful with that, since it will replace the input file. |
|
118 | 117 | |
|
119 | 118 | .. note:: |
|
120 | 119 | |
|
121 | 120 | nbconvert uses pandoc_ to convert between various markup languages, |
|
122 | 121 | so pandoc is a dependency when converting to latex or reStructuredText. |
|
123 | 122 | |
|
124 | 123 | .. _pandoc: http://johnmacfarlane.net/pandoc/ |
|
125 | 124 | |
|
126 | 125 | The output file created by ``nbconvert`` will have the same base name as |
|
127 | 126 | the notebook and will be placed in the current working directory. Any |
|
128 | 127 | supporting files (graphics, etc) will be placed in a new directory with the |
|
129 | 128 | same base name as the notebook, suffixed with ``_files``:: |
|
130 | 129 | |
|
131 | 130 | $ ipython nbconvert notebook.ipynb |
|
132 | 131 | $ ls |
|
133 | 132 | notebook.ipynb notebook.html notebook_files/ |
|
134 | 133 | |
|
135 | 134 | For simple single-file output, such as html, markdown, etc., |
|
136 | 135 | the output may be sent to standard output with:: |
|
137 | 136 | |
|
138 | 137 | $ ipython nbconvert --to markdown notebook.ipynb --stdout |
|
139 | 138 | |
|
140 | 139 | Multiple notebooks can be specified from the command line:: |
|
141 | 140 | |
|
142 | 141 | $ ipython nbconvert notebook*.ipynb |
|
143 | 142 | $ ipython nbconvert notebook1.ipynb notebook2.ipynb |
|
144 | 143 | |
|
145 | 144 | or via a list in a configuration file, say ``mycfg.py``, containing the text:: |
|
146 | 145 | |
|
147 | 146 | c = get_config() |
|
148 | 147 | c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"] |
|
149 | 148 | |
|
150 | 149 | and using the command:: |
|
151 | 150 | |
|
152 | 151 | $ ipython nbconvert --config mycfg.py |
|
153 | 152 | |
|
154 | 153 | |
|
155 | 154 | LaTeX citations |
|
156 | 155 | --------------- |
|
157 | 156 | |
|
158 | 157 | ``nbconvert`` now has support for LaTeX citations. With this capability you |
|
159 | 158 | can: |
|
160 | 159 | |
|
161 | 160 | * Manage citations using BibTeX. |
|
162 | 161 | * Cite those citations in Markdown cells using HTML data attributes. |
|
163 | 162 | * Have ``nbconvert`` generate proper LaTeX citations and run BibTeX. |
|
164 | 163 | |
|
165 | 164 | For an example of how this works, please see the citations example in |
|
166 | 165 | the nbconvert-examples_ repository. |
|
167 | 166 | |
|
168 | 167 | .. _nbconvert-examples: https://github.com/ipython/nbconvert-examples |
|
169 | 168 |
General Comments 0
You need to be logged in to leave comments.
Login now