Show More
@@ -21,18 +21,18 b' The IPython Notebook combines two components:' | |||||
21 |
|
21 | |||
22 | * **The IPython Notebook web application**: |
|
22 | * **The IPython Notebook web application**: | |
23 |
|
23 | |||
24 | The IPython Notebook web app is a browser-based tool for interactive |
|
24 | The *IPython Notebook web app* is a browser-based tool for interactive | |
25 | authoring of literate computations, in which explanatory text, mathematics, |
|
25 | authoring of literate computations, in which explanatory text, mathematics, | |
26 | computations and rich media output may be combined. Input and output are |
|
26 | computations and rich media output may be combined. Input and output are | |
27 | stored in persistent cells that may be edited in-place. |
|
27 | stored in persistent cells that may be edited in-place. | |
28 |
|
28 | |||
29 | * **Notebook documents**: |
|
29 | * **Notebook documents**: | |
30 |
|
30 | |||
31 | *Notebook documents*, or *notebooks*, are plain text documents which record |
|
31 | *Notebook documents*, or *notebooks*, are plain text documents which record | |
32 | all inputs and outputs of the computations, interspersed with text, |
|
32 | all inputs and outputs of the computations, interspersed with text, | |
33 | mathematics and HTML 5 representations of objects, in a literate style. |
|
33 | mathematics and HTML 5 representations of objects, in a literate style. | |
34 |
|
34 | |||
35 |
Since the similarity in names can lead to some confusion, in th |
|
35 | Since the similarity in names can lead to some confusion, in this documentation | |
36 | we will use capitalization of the word "notebook" to distinguish the |
|
36 | we will use capitalization of the word "notebook" to distinguish the | |
37 | *N*otebook app and *n*otebook documents, thinking of the Notebook app as being |
|
37 | *N*otebook app and *n*otebook documents, thinking of the Notebook app as being | |
38 | a proper noun. We will also always refer to the "Notebook app" when we are |
|
38 | a proper noun. We will also always refer to the "Notebook app" when we are | |
@@ -56,41 +56,45 b' Main features of the IPython Notebook web app' | |||||
56 |
|
56 | |||
57 | The main features of the IPython Notebook app include: |
|
57 | The main features of the IPython Notebook app include: | |
58 |
|
58 | |||
59 | * In-browser editing for code, with automatic syntax highlighting and |
|
59 | * In-browser editing for code, with automatic syntax highlighting and indentation and tab completion/introspection. | |
60 | indentation and tab completion/introspection. |
|
60 | ||
61 | * Literate combination of code with rich text using the Markdown markup |
|
61 | * Literate combination of code with rich text using the Markdown_ markup language. | |
62 | language. |
|
62 | ||
63 | * Mathematics is easily included within the Markdown using LaTeX notation, and |
|
63 | * Mathematics is easily included within the Markdown using LaTeX notation, and rendered natively by MathJax_. | |
64 | rendered natively by MathJax. |
|
64 | ||
65 | * Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result |
|
65 | * Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result of computations. | |
66 | of computations. |
|
66 | ||
67 | * Publication-quality figures in a range of formats (SVG / PNG), rendered by |
|
67 | * Publication-quality figures in a range of formats (SVG / PNG), rendered by the matplotlib_ library, may be included inline and exported. | |
68 | the ``matplotlib`` library, may be included inline and exported. |
|
68 | ||
|
69 | ||||
|
70 | .. _MathJax: http://www.mathjax.org/ | |||
|
71 | .. _matplotlib: http://matplotlib.org/ | |||
|
72 | .. _Markdown: http://daringfireball.net/projects/markdown/syntax | |||
69 |
|
73 | |||
70 |
|
74 | |||
71 | Notebook documents |
|
75 | Notebook documents | |
72 | ------------------ |
|
76 | ------------------ | |
73 |
|
77 | |||
74 | Notebook document files are just standard text files with the extension |
|
78 | Notebook document files are just standard, ASCII-coded text files with the extension ``.ipynb``, stored in the working directory on your computer. Since the contents of the files are just plain text, they can be easily version-controlled and shared with colleagues. | |
75 | ``.ipynb``, stored in the working directory on your computer. This file can be easily put under version control and shared with colleagues. |
|
|||
76 |
|
79 | |||
77 | Despite the fact that the notebook documents are plain text files, they use |
|
80 | Internally, notebook document files use the JSON_ format, allowing them to | |
78 | the JSON format in order to store a *complete*, *reproducible*, *one-to-one* |
|
81 | store a *complete*, *reproducible*, *one-to-one* copy of the state of the computational state as it is inside the Notebook app. | |
79 | copy of the state of the computational state as it is inside the Notebook app. |
|
|||
80 | All computations carried out, and the corresponding results obtained, can be |
|
82 | All computations carried out, and the corresponding results obtained, can be | |
81 |
combined in a literate way, |
|
83 | combined in a literate way, interleaving executable code with rich text, mathematics, and HTML 5 representations of objects. | |
82 | and HTML 5 representations of objects. |
|
84 | ||
|
85 | .. _JSON: http://en.wikipedia.org/wiki/JSON | |||
83 |
|
86 | |||
84 | Notebooks may easily be exported to a range of static formats, including |
|
87 | Notebooks may easily be exported to a range of static formats, including | |
85 | HTML (for example, for blog posts), PDF and slide shows. |
|
88 | HTML (for example, for blog posts), PDF and slide shows, via the newly-included `nbconvert script`_ functionality. | |
86 | Furthermore, any publicly available notebook may be shared via the |
|
89 | ||
87 | `IPython Notebook Viewer <http://nbviewer.ipython.org>`_ service, which will |
|
90 | Furthermore, any ``.ipynb`` notebook document with a publicly-available URL can be shared via the `IPython Notebook Viewer`_ service. This service loads the notebook document from the URL which will | |
88 |
provide it as a static web page. The results may thus be shared with |
|
91 | provide it as a static web page. The results may thus be shared with a colleague, or as a public blog post, without other users needing to install IPython themselves. | |
89 | to install anything. |
|
|||
90 |
|
92 | |||
91 | See the :ref:`installation documentation <install_index>` for directions on |
|
93 | See the :ref:`installation documentation <install_index>` for directions on | |
92 | how to install the notebook and its dependencies. |
|
94 | how to install the notebook and its dependencies. | |
93 |
|
95 | |||
|
96 | .. _`Ipython Notebook Viewer`: http://nbviewer.ipython.org | |||
|
97 | ||||
94 | .. note:: |
|
98 | .. note:: | |
95 |
|
99 | |||
96 | You can start more than one notebook server at the same time, if you want to |
|
100 | You can start more than one notebook server at the same time, if you want to | |
@@ -107,6 +111,8 b' You can start running the Notebook web app using the following command::' | |||||
107 |
|
111 | |||
108 | $ ipython notebook |
|
112 | $ ipython notebook | |
109 |
|
113 | |||
|
114 | (Here, and in the sequel, the initial ``$`` represents the shell prompt, indicating that the command is to be run from the command line in a shell.) | |||
|
115 | ||||
110 | The landing page of the notebook server application, the *dashboard*, shows |
|
116 | The landing page of the notebook server application, the *dashboard*, shows | |
111 | the notebooks currently available in the *working directory* (the directory |
|
117 | the notebooks currently available in the *working directory* (the directory | |
112 | from which the notebook was started). |
|
118 | from which the notebook was started). | |
@@ -128,7 +134,7 b' text and code cells, to get a cleaner import with the file already broken into' | |||||
128 | individual cells. |
|
134 | individual cells. | |
129 |
|
135 | |||
130 | When you open or create a new notebook, your browser tab will reflect the name |
|
136 | When you open or create a new notebook, your browser tab will reflect the name | |
131 | of that notebook, prefixed with "IPy". |
|
137 | of that notebook, prefixed by the "IPy" icon denoting that the tab corresponds to the IPython Notebook. | |
132 | The URL is currently not meant to be human-readable and is not persistent |
|
138 | The URL is currently not meant to be human-readable and is not persistent | |
133 | across invocations of the notebook server; however, this will change in a |
|
139 | across invocations of the notebook server; however, this will change in a | |
134 | future version of IPython. |
|
140 | future version of IPython. | |
@@ -164,6 +170,11 b' Toolbar' | |||||
164 | The tool bar gives a quick way of accessing the most-used operations within |
|
170 | The tool bar gives a quick way of accessing the most-used operations within | |
165 | the Notebook, by clicking on an icon. |
|
171 | the Notebook, by clicking on an icon. | |
166 |
|
172 | |||
|
173 | Creating a new notebook document | |||
|
174 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |||
|
175 | ||||
|
176 | A new notebook space/document may be created at any time, either from the dashboard, or using the `File | New` menu option from within an active notebook. The new notebook is created within the same working directory and will open in a new browser tab. It will also be reflected as a new entry in the notebook list on the dashboard. | |||
|
177 | ||||
167 |
|
178 | |||
168 | Input cells |
|
179 | Input cells | |
169 | ----------- |
|
180 | ----------- | |
@@ -209,16 +220,12 b' via your localhost address at ``127.0.0.1``), then you can just type' | |||||
209 | ``%qtconsole`` in the notebook and a Qt console will open up, connected to |
|
220 | ``%qtconsole`` in the notebook and a Qt console will open up, connected to | |
210 | that same kernel. |
|
221 | that same kernel. | |
211 |
|
222 | |||
212 |
At certain moments, it may be necessary to interrupt a |
|
223 | At certain moments, it may be necessary to interrupt a calculation which is | |
213 | calculation, or even to kill the entire computational process. This may be |
|
224 | taking too long to complete. This may be done with the ``Kernel | Interrupt`` | |
214 | achieved by interrupting or restarting the kernel, respectively. |
|
225 | menu option, or the :kbd:``Ctrl-i`` keyboard shortcut. | |
215 | After a kernel restart, it as if the notebook were loaded afresh. |
|
226 | Similarly, it may be necessary or desirable to restart the whole computational | |
216 |
|
227 | process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.`` shortcut. | ||
217 | A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the |
|
228 | This gives an equivalent state to loading the notebook document afresh. | |
218 | menu option ``File | Download as``. Choosing the ``.py`` option downloads a |
|
|||
219 | Python ``.py`` script, in which all output has been removed and the content of |
|
|||
220 | Markdown cells in comment areas. See ref:`below <notebook_format>` for more |
|
|||
221 | details on the notebook format. |
|
|||
222 |
|
229 | |||
223 |
|
230 | |||
224 | .. warning:: |
|
231 | .. warning:: | |
@@ -263,7 +270,7 b' to remember are the following:' | |||||
263 | Executes the current cell, shows the output, and inserts a *new* input |
|
270 | Executes the current cell, shows the output, and inserts a *new* input | |
264 | cell between the current cell and the adjacent cell (if one exists). This |
|
271 | cell between the current cell and the adjacent cell (if one exists). This | |
265 | is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`. |
|
272 | is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`. | |
266 |
(:kbd:`Ctrl-m a` adds a new cell |
|
273 | (:kbd:`Ctrl-m a` adds a new cell above the current one.) | |
267 |
|
274 | |||
268 | * :kbd:`Ctrl-m`: |
|
275 | * :kbd:`Ctrl-m`: | |
269 | This is the prefix for *all* other shortcuts, which consist of :kbd:`Ctrl-m` followed by a single letter or character. For example, if you type :kbd:`Ctrl-m h` (that is, the sole letter :kbd:`h` after :kbd:`Ctrl-m`), IPython will show you all the available keyboard shortcuts. |
|
276 | This is the prefix for *all* other shortcuts, which consist of :kbd:`Ctrl-m` followed by a single letter or character. For example, if you type :kbd:`Ctrl-m h` (that is, the sole letter :kbd:`h` after :kbd:`Ctrl-m`), IPython will show you all the available keyboard shortcuts. | |
@@ -294,7 +301,7 b' When a code cell is executed with :kbd:`Shift-Enter`, the code that it' | |||||
294 | contains is transparently exported and run in that language (with automatic |
|
301 | contains is transparently exported and run in that language (with automatic | |
295 | compiling, etc., if necessary). The result that is returned from this |
|
302 | compiling, etc., if necessary). The result that is returned from this | |
296 | computation is then displayed in the notebook space as the cell's |
|
303 | computation is then displayed in the notebook space as the cell's | |
297 |
*output*. If this output is of a textual nature, |
|
304 | *output*. If this output is of a textual nature, it is placed into a | |
298 | numbered *output cell*. However, many other possible forms of output are also |
|
305 | numbered *output cell*. However, many other possible forms of output are also | |
299 | possible, including ``matplotlib`` figures and HTML tables (as used, for |
|
306 | possible, including ``matplotlib`` figures and HTML tables (as used, for | |
300 | example, in the ``pandas`` data analyis package). This is known as IPython's |
|
307 | example, in the ``pandas`` data analyis package). This is known as IPython's | |
@@ -318,11 +325,14 b' rich text. Markdown allows arbitrary HTML code for formatting.' | |||||
318 |
|
325 | |||
319 | Within Markdown cells, you can also include *mathematics* in a straightforward |
|
326 | Within Markdown cells, you can also include *mathematics* in a straightforward | |
320 | way, using standard LaTeX notation: ``$...$`` for inline mathematics and |
|
327 | way, using standard LaTeX notation: ``$...$`` for inline mathematics and | |
321 | ``$$...$$`` for displayed mathematics. Mathematics is rendered natively in the |
|
328 | ``$$...$$`` for displayed mathematics. When the Markdown cell is executed, the LaTeX portions are automatically rendered in the HTML output as equations with high quality typography. This is made possible by MathJax_, which supports a `large subset`_ of LaTeX functionality | |
322 | browser by MathJax. Standard LaTeX and AMS-math environments, such as |
|
329 | ||
323 | ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}`` |
|
330 | .. _`large subset`: http://docs.mathjax.org/en/latest/tex.html | |
324 | also work, and new LaTeX macros may be defined using standard LaTeX methods, |
|
331 | ||
325 | such as ``\newcommand``, by placing them anywhere in a Markdown cell. |
|
332 | Standard mathematics environments defined by LaTeX and AMS-LaTeX (the `amsmath` package) also work, such as | |
|
333 | ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``. | |||
|
334 | New LaTeX macros may be defined using standard methods, | |||
|
335 | such as ``\newcommand``, by placing them anywhere *between math delimiters* in a Markdown cell. These definitions are then available throughout the rest of the IPython session. (Note, however, that more care must be taken when using the `nbconvert script`_ to output to LaTeX). | |||
326 |
|
336 | |||
327 | Raw input cells |
|
337 | Raw input cells | |
328 | ~~~~~~~~~~~~~~~ |
|
338 | ~~~~~~~~~~~~~~~ | |
@@ -336,7 +346,7 b' Heading cells' | |||||
336 | ~~~~~~~~~~~~~ |
|
346 | ~~~~~~~~~~~~~ | |
337 | You can provide a conceptual structure for your computational document as a |
|
347 | You can provide a conceptual structure for your computational document as a | |
338 | whole using different levels of headings; there are 6 levels available, from |
|
348 | whole using different levels of headings; there are 6 levels available, from | |
339 |
level 1 ( |
|
349 | level 1 (top level) down to level 6 (paragraph). These can be used later for | |
340 | constructing tables of contents, etc. |
|
350 | constructing tables of contents, etc. | |
341 |
|
351 | |||
342 | As with Markdown cells, a heading input cell is replaced by a rich text |
|
352 | As with Markdown cells, a heading input cell is replaced by a rich text | |
@@ -354,48 +364,64 b' the computational state in certain ways.' | |||||
354 |
|
364 | |||
355 | There are two types of magics: |
|
365 | There are two types of magics: | |
356 |
|
366 | |||
357 | **line magics**: |
|
367 | - **line magics**: | |
|
368 | ||||
358 | These begin with a single ``%`` and take as arguments the rest of the |
|
369 | These begin with a single ``%`` and take as arguments the rest of the | |
359 | *same line* of the code cell. Any other lines of the code cell are |
|
370 | *same line* of the code cell. Any other lines of the code cell are | |
360 | treated as if they were part of a standard code cell. |
|
371 | treated as if they were part of a standard code cell. | |
361 |
|
372 | |||
362 | **cell magics**: |
|
373 | - **cell magics**: | |
363 | These begin with ``%%`` and operate on the *entire* remaining contents of |
|
374 | ||
364 | the code cell. |
|
375 | These begin with ``%%`` and operate on the *entire* remaining contents of | |
|
376 | the code cell. | |||
365 |
|
377 | |||
366 | Line magics |
|
378 | Line magics | |
367 | ~~~~~~~~~~~ |
|
379 | ~~~~~~~~~~~ | |
368 | Some of the available line magics are the following: |
|
380 | Some of the available line magics are the following: | |
369 |
|
381 | |||
370 | * ``%load filename``: |
|
382 | * ``%load filename``: | |
371 | Loads the contents of the file ``filename`` into a new code cell. |
|
|||
372 |
|
383 | |||
373 | * ``%timeit code``: |
|
384 | Loads the contents of the file ``filename`` into a new code cell. This | |
374 | A simple way to time how long the single line of code ``code`` takes to run |
|
385 | can be a URL for a remote file. | |
|
386 | ||||
|
387 | * ``%timeit code``: | |||
|
388 | ||||
|
389 | An easy way to time how long the single line of code ``code`` takes to run | |||
375 |
|
390 | |||
376 | * ``%config``: |
|
391 | * ``%config``: | |
377 | Configuration of the IPython Notebook |
|
392 | ||
|
393 | Configuration of the IPython Notebook | |||
378 |
|
394 | |||
379 | * ``%lsmagic``: |
|
395 | * ``%lsmagic``: | |
380 | Provides a list of all available magic commands |
|
396 | ||
|
397 | Provides a list of all available magic commands | |||
381 |
|
398 | |||
382 | Cell magics |
|
399 | Cell magics | |
383 | ~~~~~~~~~~~ |
|
400 | ~~~~~~~~~~~ | |
384 |
|
401 | |||
385 | * ``%%latex``: |
|
402 | * ``%%latex``: | |
386 | Renders the entire contents of the cell in LaTeX, without needing to use |
|
403 | ||
387 | explicit LaTeX delimiters. |
|
404 | Renders the entire contents of the cell in LaTeX, without needing to use | |
|
405 | explicit LaTeX delimiters. | |||
388 |
|
406 | |||
389 | * ``%%bash``: |
|
407 | * ``%%bash``: | |
390 | The code cell is executed by sending it to be executed by ``bash``. The |
|
408 | ||
391 | output of the ``bash`` commands is captured and displayed in the notebook. |
|
409 | The code cell is executed by sending it to be executed by ``bash``. The | |
|
410 | output of the ``bash`` commands is captured and displayed in the notebook. | |||
392 |
|
411 | |||
393 | * ``%%file filename``: |
|
412 | * ``%%file filename``: | |
394 | Writes the contents of the cell to the file ``filename``. |
|
413 | ||
395 | **Caution**: The file is over-written without warning! |
|
414 | Writes the contents of the cell to the file ``filename``. | |
|
415 | **Caution**: The file is over-written without warning! | |||
396 |
|
416 | |||
397 | * ``%%R``: |
|
417 | * ``%%R``: | |
398 | Execute the contents of the cell using the R language. |
|
418 | ||
|
419 | Execute the contents of the cell using the R language. | |||
|
420 | ||||
|
421 | * ``%%timeit``: | |||
|
422 | ||||
|
423 | Version of ``%timeit`` which times the entire block of code in the current code cell. | |||
|
424 | ||||
399 |
|
425 | |||
400 |
|
426 | |||
401 | Several of the cell magics provide functionality to manipulate the filesystem |
|
427 | Several of the cell magics provide functionality to manipulate the filesystem | |
@@ -404,10 +430,10 b' of a remote server to which you otherwise do not have access.' | |||||
404 |
|
430 | |||
405 | Plotting |
|
431 | Plotting | |
406 | -------- |
|
432 | -------- | |
407 |
One major feature of the Notebook is the ability to |
|
433 | One major feature of the Notebook is the ability to interact with | |
408 | plots as *inline* output, thus displaying the result of running some code |
|
434 | plots that are the output of running code cells. IPython is designed to work | |
409 | right next to the code itself. IPython is designed to work seamlessly with the |
|
435 | seamlessly with the ``matplotlib`` plotting library to provide this | |
410 | ``matplotlib`` plotting library to attain this functionality. |
|
436 | functionality. | |
411 |
|
437 | |||
412 | To set this up, before any plotting is performed you must execute the |
|
438 | To set this up, before any plotting is performed you must execute the | |
413 | ``%matplotlib`` magic command. This performs the necessary behind-the-scenes |
|
439 | ``%matplotlib`` magic command. This performs the necessary behind-the-scenes | |
@@ -418,45 +444,58 b' names are added to the namespace.' | |||||
418 | For more agile *interactive* use of the notebook space, an alternative magic, |
|
444 | For more agile *interactive* use of the notebook space, an alternative magic, | |
419 | ``%pylab``, is provided. This does the same work as the ``%matplotlib`` magic, |
|
445 | ``%pylab``, is provided. This does the same work as the ``%matplotlib`` magic, | |
420 | but *in addition* it automatically executes a standard sequence of ``import`` |
|
446 | but *in addition* it automatically executes a standard sequence of ``import`` | |
421 |
statements required to work with the ``%matplotlib`` library |
|
447 | statements required to work with the ``%matplotlib`` library, importing the | |
|
448 | following names into the namespace: | |||
422 |
|
449 | |||
423 | It will import at the top level `numpy` as `np`, `pyplot` as `plt`, |
|
450 | ``numpy`` as ``np``; ``matplotlib.pyplot`` as ``plt``; | |
424 |
`matplotlib`, `pylab` and `mlab` from `matplotlib` |
|
451 | ``matplotlib``, ``pylab`` and ``mlab`` from ``matplotlib``; and *all names* | |
425 | from ``numpy`` and ``pylab``. A less invasive, but less interactive, option is |
|
452 | from within ``numpy`` and ``pylab``. | |
426 | ``%pylab --no-import-all``, which does not do these ``import *`` imports. |
|
|||
427 |
|
453 | |||
428 | When the default ``%matplotlib`` or ``%pylab`` magics are used, the output of |
|
454 | However, the use of ``%pylab`` is discouraged, since names coming from | |
429 | a plotting command is captured in a *separate* window. An alternative is to |
|
455 | different packages may collide. In general, the use of ``from package import | |
430 | use:: |
|
456 | *`` is discouraged. A better option is then:: | |
|
457 | ||||
|
458 | %pylab --no-import-all | |||
431 |
|
459 | |||
432 | %matplotlib inline |
|
460 | which imports the names listed above, but does *not* perform this ``import *`` | |
|
461 | imports. | |||
|
462 | ||||
|
463 | If the ``%matplotlib`` or ``%pylab` magics are called without an argument, the | |||
|
464 | output of a plotting command is displayed using the default ``matplotlib`` | |||
|
465 | backend in a separate window. Alternatively, the backend can be explicitly | |||
|
466 | requested using, for example:: | |||
|
467 | ||||
|
468 | %matplotlib gtk | |||
433 |
|
469 | |||
434 | or:: |
|
470 | A particularly interesting backend is the ``inline`` backend. | |
|
471 | This is applicable only for the IPython Notebook and the IPython Qtconsole. | |||
|
472 | It can be invoked as follows:: | |||
|
473 | ||||
|
474 | %matplotlib inline | |||
435 |
|
475 | |||
436 | %pylab inline |
|
476 | With this backend, output of plotting commands is displayed *inline* within | |
|
477 | the notebook format, directly below the input cell that produced it. The resulting plots will then also be stored in the notebook document. This provides a key part of the functionality for reproducibility_ that the IPython Notebook provides. | |||
437 |
|
478 | |||
438 | These instead capture the output of the plot and display it *inline* within |
|
479 | .. _reproducibility: https://en.wikipedia.org/wiki/Reproducibility | |
439 | the notebook format, below the input cell that produced it. The resulting |
|
|||
440 | plots will then also be stored in the notebook document. |
|
|||
441 |
|
480 | |||
|
481 | .. _`nbconvert script`: | |||
442 |
|
482 | |||
443 | Converting notebooks to other formats |
|
483 | Converting notebooks to other formats | |
444 | ------------------------------------- |
|
484 | ------------------------------------- | |
445 | Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which |
|
485 | Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which | |
446 |
allows you to convert an ``.ipynb`` notebook document file into a |
|
486 | allows you to convert an ``.ipynb`` notebook document file into various static | |
447 | format. |
|
487 | formats. | |
448 |
|
488 | |||
449 | Currently, only a command line tool is provided; in the future, it will also |
|
489 | Currently, ``nbconvert`` is provided as a command line tool, run as a script using IPython. In the future, a direct export capability from within the IPython Notebook web app is planned. | |
450 | be possible to export from within the Notebook app. The command line syntax |
|
490 | ||
451 | is:: |
|
491 | The command-line syntax to run the ``nbconvert`` script is:: | |
452 |
|
492 | |||
453 | $ ipython nbconvert --format=FORMAT notebook.ipynb |
|
493 | $ ipython nbconvert --format=FORMAT notebook.ipynb | |
454 |
|
494 | |||
455 | This will convert the IPython document file ``notebook.ipynb`` into the output |
|
495 | This will convert the IPython document file ``notebook.ipynb`` into the output | |
456 | format given by the ``FORMAT`` string. |
|
496 | format given by the ``FORMAT`` string. | |
457 |
|
497 | |||
458 |
The default output format is HTML, for which the `--format`` modifier |
|
498 | The default output format is HTML, for which the ``--format`` modifier may be omitted:: | |
459 | actually required:: |
|
|||
460 |
|
499 | |||
461 | $ ipython nbconvert notebook.ipynb |
|
500 | $ ipython nbconvert notebook.ipynb | |
462 |
|
501 | |||
@@ -464,57 +503,59 b' The currently supported export formats are the following:' | |||||
464 |
|
503 | |||
465 | * HTML: |
|
504 | * HTML: | |
466 |
|
505 | |||
467 |
- |
|
506 | - **full_html**: | |
468 | Standard HTML |
|
507 | Standard HTML | |
469 |
|
508 | |||
470 |
- |
|
509 | - **simple_html**: | |
471 | Simplified HTML |
|
510 | Simplified HTML | |
472 |
|
511 | |||
473 |
- |
|
512 | - **reveal**: | |
474 | HTML slideshow presentation for use with the ``reveal.js`` package |
|
513 | HTML slideshow presentation for use with the ``reveal.js`` package | |
475 |
|
514 | |||
476 | * PDF: |
|
515 | * PDF: | |
477 |
|
516 | |||
478 |
- |
|
517 | - **sphinx_howto**: | |
479 | The format for Sphinx HOWTOs; similar to an ``article`` in LaTeX |
|
518 | The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX | |
480 |
|
519 | |||
481 |
- |
|
520 | - **sphinx_manual**: | |
482 | The format for Sphinx manuals; similar to a `book`` in LaTeX |
|
521 | The format for Sphinx_ manuals; similar to a ``book`` in LaTeX | |
483 |
|
522 | |||
484 |
- |
|
523 | - **latex**: | |
485 | An article formatted completely using LaTeX |
|
524 | An article formatted completely using LaTeX | |
486 |
|
525 | |||
487 | * Markup: |
|
526 | * Markup: | |
488 |
|
527 | |||
489 |
- |
|
528 | - **rst**: | |
490 | reStructuredText markup |
|
529 | reStructuredText_ markup | |
|
530 | ||||
|
531 | - **markdown**: | |||
|
532 | Markdown_ markup | |||
491 |
|
533 | |||
492 | - ``markdown``: |
|
534 | .. _Sphinx: http://sphinx-doc.org/ | |
493 | Markdown markup |
|
535 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
494 |
|
536 | |||
495 | * Python: |
|
537 | * Python: | |
496 |
|
538 | |||
497 |
Comments out all the non-Python code to produce a |
|
539 | Comments out all the non-Python code to produce a ``.py`` Python | |
498 | script with just the code content. |
|
540 | script with just the code content. Currently the output includes IPython magics, and so can be run with ``ipython``, after changing the extension of the script to ``.ipy``. | |
499 |
|
541 | |||
500 |
The files output by ``nbconvert` |
|
542 | The files output by ``nbconvert`` are all placed in a new subdirectory | |
501 | called ``nbconvert_build``. |
|
543 | called ``nbconvert_build``. | |
502 |
|
544 | |||
503 |
Each of the options for PDF export produces as an intermediate step a |
|
545 | Each of the options for PDF export produces as an intermediate step a LaTeX | |
504 |
|
|
546 | ``.tex`` file with the same basename as the notebook, as well as individual | |
505 | files for each figure, and ``.text` files with textual output from running |
|
547 | files for each figure, and ``.text` files with textual output from running | |
506 | code cells; all of these files are located together in the ``nbconvert_build`` |
|
548 | code cells. | |
507 | subdirectory. |
|
|||
508 |
|
549 | |||
509 | To actually produce the final PDF file, run the following commands:: |
|
550 | To actually produce the final PDF file, run the following commands:: | |
510 |
|
551 | |||
511 | $ cd nbconvert_build |
|
552 | $ cd nbconvert_build | |
512 | $ pdflatex notebook |
|
553 | $ pdflatex notebook | |
513 |
|
554 | |||
514 |
This requires a local installation of LaTeX on your machine |
|
555 | This requires a local installation of LaTeX on your machine. | |
515 | PDF file ``notebook.pdf``, also inside the ``nbconvert_build`` subdirectory. |
|
556 | The output is a PDF file ``notebook.pdf``, also placed inside the ``nbconvert_build`` subdirectory. | |
516 |
|
557 | |||
517 |
Alternatively, the output may be |
|
558 | Alternatively, the output may be sent to standard output with:: | |
518 |
|
559 | |||
519 | $ ipython nbconvert mynotebook.ipynb --stdout |
|
560 | $ ipython nbconvert mynotebook.ipynb --stdout | |
520 |
|
561 | |||
@@ -560,31 +601,34 b' on available options, use::' | |||||
560 | Extracting standard Python files from notebooks |
|
601 | Extracting standard Python files from notebooks | |
561 | ----------------------------------------------- |
|
602 | ----------------------------------------------- | |
562 | ``.ipynb`` notebook document files are plain text files which store a |
|
603 | ``.ipynb`` notebook document files are plain text files which store a | |
563 |
representation in JSON format of the contents of a notebook space. As such, |
|
604 | representation in JSON format of the contents of a notebook space. As such, | |
564 |
|
|
605 | they are not valid ``.py`` Python scripts, and so can be neither imported | |
565 |
``import`` in Python, nor run as a standard Python |
|
606 | directly with ``import`` in Python, nor run directly as a standard Python | |
|
607 | script (though both of these are possible with simple workarounds). | |||
566 |
|
608 | |||
567 | To extract just the Python code from within a notebook document, one option is |
|
609 | ||
568 | to use ``ipython nbconvert``, as described above. |
|
610 | To extract the Python code from within a notebook document, the simplest method is to use the ``File | Download as | Python (.py)`` menu item; the resulting ``.py`` script will be downloaded to your browser's default download location. | |
569 |
|
611 | |||
570 | An alternative is to pass an argument to the IPython Notebook, from the moment |
|
612 | An alternative is to pass an argument to the IPython Notebook, from the moment | |
571 | when it is originally started, specifying that whenever it saves an ``.ipynb`` |
|
613 | when it is originally started, specifying that whenever it saves an ``.ipynb`` | |
572 | notebook document, it should, at the same time, save the corresponding |
|
614 | notebook document, it should, at the same time, save the corresponding | |
573 |
|
|
615 | ``.py`` script. To do so, you can execute the following command:: | |
574 |
|
616 | |||
575 | ipython notebook --script |
|
617 | $ ipython notebook --script | |
576 |
|
618 | |||
577 | or you can set this option permanently in your configuration file with:: |
|
619 | or you can set this option permanently in your configuration file with:: | |
578 |
|
620 | |||
579 | c = get_config() |
|
621 | c = get_config() | |
580 | c.NotebookManager.save_script=True |
|
622 | c.NotebookManager.save_script=True | |
581 |
|
623 | |||
582 |
The result is that standard ``.py`` files are also now generated, |
|
624 | The result is that standard ``.py`` files are also now generated, which | |
583 | can be ``%run``, imported from regular IPython sessions or other notebooks, or |
|
625 | can be ``%run``, imported from regular IPython sessions or other notebooks, or | |
584 | executed at the command line, as usual. Since the raw code you have typed is |
|
626 | executed at the command line, as usual. Since the raw code you have typed is | |
585 | exported you must avoid using syntax such as IPython magics and other IPython- |
|
627 | exported, you must avoid using syntax such as IPython magics and other IPython- | |
586 | specific extensions to the language for the files to be able to be |
|
628 | specific extensions to the language for the files to be able to be | |
587 | successfully imported. |
|
629 | successfully imported; or you can change the script's extension to ``.ipy`` and run it with:: | |
|
630 | ||||
|
631 | $ ipython script.ipy | |||
588 |
|
632 | |||
589 | In normal Python practice, the standard way to differentiate importable code |
|
633 | In normal Python practice, the standard way to differentiate importable code | |
590 | in a Python script from the "executable" part of a script is to use the |
|
634 | in a Python script from the "executable" part of a script is to use the |
General Comments 0
You need to be logged in to leave comments.
Login now