##// END OF EJS Templates
Document how to install kernel spec files...
Jan Schulz -
Show More
@@ -1,482 +1,502 b''
1 1 .. _htmlnotebook:
2 2
3 3 The IPython Notebook
4 4 ====================
5 5
6 6 Introduction
7 7 ------------
8 8
9 9 The notebook extends the console-based approach to interactive computing in
10 10 a qualitatively new direction, providing a web-based application suitable for
11 11 capturing the whole computation process: developing, documenting, and
12 12 executing code, as well as communicating the results. The IPython notebook
13 13 combines two components:
14 14
15 15 **A web application**: a browser-based tool for interactive authoring of
16 16 documents which combine explanatory text, mathematics, computations and their
17 17 rich media output.
18 18
19 19 **Notebook documents**: a representation of all content visible in the web
20 20 application, including inputs and outputs of the computations, explanatory
21 21 text, mathematics, images, and rich media representations of objects.
22 22
23 23 .. seealso::
24 24
25 25 See the :ref:`installation documentation <installnotebook>` for directions
26 26 on how to install the notebook and its dependencies.
27 27
28 28
29 29 Main features of the web application
30 30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31 31
32 32 * In-browser editing for code, with automatic syntax highlighting,
33 33 indentation, and tab completion/introspection.
34 34
35 35 * The ability to execute code from the browser, with the results of
36 36 computations attached to the code which generated them.
37 37
38 38 * Displaying the result of computation using rich media representations, such
39 39 as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
40 40 rendered by the matplotlib_ library, can be included inline.
41 41
42 42 * In-browser editing for rich text using the Markdown_ markup language, which
43 43 can provide commentary for the code, is not limited to plain text.
44 44
45 45 * The ability to easily include mathematical notation within markdown cells
46 46 using LaTeX, and rendered natively by MathJax_.
47 47
48 48
49 49
50 50 .. _MathJax: http://www.mathjax.org/
51 51
52 52
53 53 Notebook documents
54 54 ~~~~~~~~~~~~~~~~~~
55 55 Notebook documents contains the inputs and outputs of a interactive session as
56 56 well as additional text that accompanies the code but is not meant for
57 57 execution. In this way, notebook files can serve as a complete computational
58 58 record of a session, interleaving executable code with explanatory text,
59 59 mathematics, and rich representations of resulting objects. These documents
60 60 are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
61 61 JSON is a plain text format, they can be version-controlled and shared with
62 62 colleagues.
63 63
64 64 .. _JSON: http://en.wikipedia.org/wiki/JSON
65 65
66 66 Notebooks may be exported to a range of static formats, including HTML (for
67 67 example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
68 68 the new :ref:`nbconvert <nbconvert>` command.
69 69
70 70 Furthermore, any ``.ipynb`` notebook document available from a public
71 71 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
72 72 This service loads the notebook document from the URL and renders it as a
73 73 static web page. The results may thus be shared with a colleague, or as a
74 74 public blog post, without other users needing to install IPython themselves.
75 75 In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
76 76 so you can do your own static conversions with nbconvert, without relying on
77 77 nbviewer.
78 78
79 79
80 80
81 81 .. seealso::
82 82
83 83 :ref:`Details on the notebook JSON file format <nbformat>`
84 84
85 85
86 86 Starting the notebook server
87 87 ----------------------------
88 88
89 89 You can start running a notebook server from the command line using the
90 90 following command::
91 91
92 92 ipython notebook
93 93
94 94 This will print some information about the notebook server in your console,
95 95 and open a web browser to the URL of the web application (by default,
96 96 ``http://127.0.0.1:8888``).
97 97
98 98 The landing page of the IPython notebook web application, the **dashboard**,
99 99 shows the notebooks currently available in the notebook directory (by default,
100 100 the directory from which the notebook server was started).
101 101
102 102 You can create new notebooks from the dashboard with the ``New Notebook``
103 103 button, or open existing ones by clicking on their name. You can also drag
104 104 and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
105 105 into the notebook list area.
106 106
107 107 When starting a notebook server from the command line, you can also open a
108 108 particular notebook directly, bypassing the dashboard, with ``ipython notebook
109 109 my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
110 110 given.
111 111
112 112 When you are inside an open notebook, the `File | Open...` menu option will
113 113 open the dashboard in a new browser tab, to allow you to open another notebook
114 114 from the notebook directory or to create a new notebook.
115 115
116 116
117 117 .. note::
118 118
119 119 You can start more than one notebook server at the same time, if you want
120 120 to work on notebooks in different directories. By default the first
121 121 notebook server starts on port 8888, and later notebook servers search for
122 122 ports near that one. You can also manually specify the port with the
123 123 ``--port`` option.
124 124
125 125 Creating a new notebook document
126 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127 127
128 128 A new notebook may be created at any time, either from the dashboard, or using
129 129 the `File | New` menu option from within an active notebook. The new notebook
130 130 is created within the same directory and will open in a new browser tab. It
131 131 will also be reflected as a new entry in the notebook list on the dashboard.
132 132
133 133
134 134 Opening notebooks
135 135 ~~~~~~~~~~~~~~~~~
136 136 An open notebook has **exactly one** interactive session connected to an
137 137 :ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
138 138 and communicate back results. This kernel remains active if the web browser
139 139 window is closed, and reopening the same notebook from the dashboard will
140 140 reconnect the web application to the same kernel. In the dashboard, notebooks
141 141 with an active kernel have a ``Shutdown`` button next to them, whereas
142 142 notebooks without an active kernel have a ``Delete`` button in its place.
143 143
144 144 Other clients may connect to the same underlying IPython kernel.
145 145 The notebook server always prints to the terminal the full details of
146 146 how to connect to each kernel, with messages such as the following::
147 147
148 148 [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
149 149
150 150 This long string is the kernel's ID which is sufficient for getting the
151 151 information necessary to connect to the kernel. You can also request this
152 152 connection data by running the ``%connect_info`` :ref:`magic
153 153 <magics_explained>`. This will print the same ID information as well as the
154 154 content of the JSON data structure it contains.
155 155
156 156 You can then, for example, manually start a Qt console connected to the *same*
157 157 kernel from the command line, by passing a portion of the ID::
158 158
159 159 $ ipython qtconsole --existing 87f7d2c0
160 160
161 161 Without an ID, ``--existing`` will connect to the most recently
162 162 started kernel. This can also be done by running the ``%qtconsole``
163 163 :ref:`magic <magics_explained>` in the notebook.
164 164
165 165 .. seealso::
166 166
167 167 :ref:`ipythonzmq`
168 168
169 169 Notebook user interface
170 170 -----------------------
171 171
172 172 When you create a new notebook document, you will be presented with the
173 173 **notebook name**, a **menu bar**, a **toolbar** and an empty **code
174 174 cell**.
175 175
176 176 **notebook name**: The name of the notebook document is displayed at the top
177 177 of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
178 178 of the ``.ipynb`` notebook document file. Clicking on the notebook name
179 179 brings up a dialog which allows you to rename it. Thus, renaming a notebook
180 180 from "Untitled0" to "My first notebook" in the browser, renames the
181 181 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
182 182
183 183 **menu bar**: The menu bar presents different options that may be used to
184 184 manipulate the way the notebook functions.
185 185
186 186 **toolbar**: The tool bar gives a quick way of performing the most-used
187 187 operations within the notebook, by clicking on an icon.
188 188
189 189 **code cell**: the default type of cell, read on for an explanation of cells
190 190
191 191
192 192 Structure of a notebook document
193 193 --------------------------------
194 194
195 195 The notebook consists of a sequence of cells. A cell is a multi-line
196 196 text input field, and its contents can be executed by using
197 197 :kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
198 198 `Cell | Run` in the menu bar. The execution behavior of a cell is determined
199 199 the cell's type. There are four types of cells: **code cells**, **markdown
200 200 cells**, **raw cells** and **heading cells**. Every cell starts off
201 201 being a **code cell**, but its type can be changed by using a dropdown on the
202 202 toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
203 203 <keyboard-shortcuts>`.
204 204
205 205 For more information on the different things you can do in a notebook,
206 206 see the `collection of examples
207 207 <http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/Notebook/Index.ipynb>`_.
208 208
209 209 Code cells
210 210 ~~~~~~~~~~
211 211 A *code cell* allows you to edit and write new code, with full syntax
212 212 highlighting and tab completion. By default, the language associated to a code
213 213 cell is Python, but other languages, such as ``Julia`` and ``R``, can be
214 214 handled using :ref:`cell magic commands <magics_explained>`.
215 215
216 216 When a code cell is executed, code that it contains is sent to the kernel
217 217 associated with the notebook. The results that are returned from this
218 218 computation are then displayed in the notebook as the cell's *output*. The
219 219 output is not limited to text, with many other possible forms of output are
220 220 also possible, including ``matplotlib`` figures and HTML tables (as used, for
221 221 example, in the ``pandas`` data analysis package). This is known as IPython's
222 222 *rich display* capability.
223 223
224 224 .. seealso::
225 225
226 226 `Basic Output`_ example notebook
227 227
228 228 `Rich Display System`_ example notebook
229 229
230 230 Markdown cells
231 231 ~~~~~~~~~~~~~~
232 232 You can document the computational process in a literate way, alternating
233 233 descriptive text with code, using *rich text*. In IPython this is accomplished
234 234 by marking up text with the Markdown language. The corresponding cells are
235 235 called *Markdown cells*. The Markdown language provides a simple way to
236 236 perform this text markup, that is, to specify which parts of the text should
237 237 be emphasized (italics), bold, form lists, etc.
238 238
239 239
240 240 When a Markdown cell is executed, the Markdown code is converted into
241 241 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
242 242 formatting.
243 243
244 244 Within Markdown cells, you can also include *mathematics* in a straightforward
245 245 way, using standard LaTeX notation: ``$...$`` for inline mathematics and
246 246 ``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
247 247 the LaTeX portions are automatically rendered in the HTML output as equations
248 248 with high quality typography. This is made possible by MathJax_, which
249 249 supports a `large subset <mathjax_tex>`_ of LaTeX functionality
250 250
251 251 .. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html
252 252
253 253 Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
254 254 `amsmath` package) also work, such as
255 255 ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
256 256 New LaTeX macros may be defined using standard methods,
257 257 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
258 258 a Markdown cell. These definitions are then available throughout the rest of
259 259 the IPython session.
260 260
261 261 .. seealso::
262 262
263 263 `Markdown Cells`_ example notebook
264 264
265 265 Raw cells
266 266 ~~~~~~~~~
267 267
268 268 *Raw* cells provide a place in which you can write *output* directly.
269 269 Raw cells are not evaluated by the notebook.
270 270 When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
271 271 destination format unmodified. For example, this allows you to type full LaTeX
272 272 into a raw cell, which will only be rendered by LaTeX after conversion by
273 273 nbconvert.
274 274
275 275 Heading cells
276 276 ~~~~~~~~~~~~~
277 277
278 278 You can provide a conceptual structure for your computational document as a
279 279 whole using different levels of headings; there are 6 levels available, from
280 280 level 1 (top level) down to level 6 (paragraph). These can be used later for
281 281 constructing tables of contents, etc. As with Markdown cells, a heading
282 282 cell is replaced by a rich text rendering of the heading when the cell is
283 283 executed.
284 284
285 285
286 286 Basic workflow
287 287 --------------
288 288
289 289 The normal workflow in a notebook is, then, quite similar to a standard
290 290 IPython session, with the difference that you can edit cells in-place multiple
291 291 times until you obtain the desired results, rather than having to
292 292 rerun separate scripts with the ``%run`` magic command.
293 293
294 294
295 295 Typically, you will work on a computational problem in pieces, organizing
296 296 related ideas into cells and moving forward once previous parts work
297 297 correctly. This is much more convenient for interactive exploration than
298 298 breaking up a computation into scripts that must be executed together, as was
299 299 previously necessary, especially if parts of them take a long time to run.
300 300
301 301 At certain moments, it may be necessary to interrupt a calculation which is
302 302 taking too long to complete. This may be done with the `Kernel | Interrupt`
303 303 menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
304 304 Similarly, it may be necessary or desirable to restart the whole computational
305 305 process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
306 306 shortcut.
307 307
308 308 A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
309 309 menu option `File | Download as`. Choosing the ``.py`` option downloads a
310 310 Python ``.py`` script, in which all rich output has been removed and the
311 311 content of markdown cells have been inserted as comments.
312 312
313 313 .. seealso::
314 314
315 315 `Running Code in the IPython Notebook`_ example notebook
316 316
317 317 `Basic Output`_ example notebook
318 318
319 319 :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
320 320
321 321 .. _keyboard-shortcuts:
322 322
323 323 Keyboard shortcuts
324 324 ~~~~~~~~~~~~~~~~~~
325 325 All actions in the notebook can be performed with the mouse, but keyboard
326 326 shortcuts are also available for the most common ones. The essential shortcuts
327 327 to remember are the following:
328 328
329 329 * :kbd:`Shift-Enter`: run cell
330 330 Execute the current cell, show output (if any), and jump to the next cell
331 331 below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
332 332 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
333 333 on its own *never* forces execution, but rather just inserts a new line in
334 334 the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
335 335 ``Cell | Run`` menu item.
336 336
337 337 * :kbd:`Ctrl-Enter`: run cell in-place
338 338 Execute the current cell as if it were in "terminal mode", where any
339 339 output is shown, but the cursor *remains* in the current cell. The cell's
340 340 entire contents are selected after execution, so you can just start typing
341 341 and only the new input will be in the cell. This is convenient for doing
342 342 quick experiments in place, or for querying things like filesystem
343 343 content, without needing to create additional cells that you may not want
344 344 to be saved in the notebook.
345 345
346 346 * :kbd:`Alt-Enter`: run cell, insert below
347 347 Executes the current cell, shows the output, and inserts a *new*
348 348 cell between the current cell and the cell below (if one exists). This
349 349 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
350 350 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
351 351
352 352 * :kbd:`Esc` and :kbd:`Enter`: Command mode and edit mode
353 353 In command mode, you can easily navigate around the notebook using keyboard
354 354 shortcuts. In edit mode, you can edit text in cells.
355 355
356 356 For the full list of available shortcuts, click :guilabel:`Help`,
357 357 :guilabel:`Keyboard Shortcuts` in the notebook menus.
358 358
359 359 Plotting
360 360 --------
361 361 One major feature of the notebook is the ability to display plots that are the
362 362 output of running code cells. IPython is designed to work seamlessly with the
363 363 matplotlib_ plotting library to provide this functionality.
364 364
365 365 To set this up, before any plotting is performed you must execute the
366 366 ``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
367 367 necessary behind-the-scenes setup for IPython to work correctly hand in hand
368 368 with ``matplotlib``; it does *not*, however, actually execute any Python
369 369 ``import`` commands, that is, no names are added to the namespace.
370 370
371 371 If the ``%matplotlib`` magic is called without an argument, the
372 372 output of a plotting command is displayed using the default ``matplotlib``
373 373 backend in a separate window. Alternatively, the backend can be explicitly
374 374 requested using, for example::
375 375
376 376 %matplotlib gtk
377 377
378 378 A particularly interesting backend, provided by IPython, is the ``inline``
379 379 backend. This is available only for the IPython Notebook and the
380 380 :ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
381 381
382 382 %matplotlib inline
383 383
384 384 With this backend, the output of plotting commands is displayed *inline*
385 385 within the notebook, directly below the code cell that produced it. The
386 386 resulting plots will then also be stored in the notebook document.
387 387
388 388 .. seealso::
389 389
390 390 `Plotting with Matplotlib`_ example notebook
391 391
392 392
393 393 Configuring the IPython Notebook
394 394 --------------------------------
395 395 The notebook server can be run with a variety of command line arguments.
396 396 To see a list of available options enter::
397 397
398 398 $ ipython notebook --help
399 399
400 400 Defaults for these options can also be set by creating a file named
401 401 ``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
402 402 folder is a subfolder of your IPython directory; to find out where it is
403 403 located, run::
404 404
405 405 $ ipython locate
406 406
407 407 To create a new set of default configuration files, with lots of information
408 408 on available options, use::
409 409
410 410 $ ipython profile create
411 411
412 412 .. seealso::
413 413
414 414 :ref:`config_overview`, in particular :ref:`Profiles`.
415 415
416 416 :ref:`notebook_server_security`
417 417
418 418 :ref:`notebook_public_server`
419 419
420 Installing new kernels
421 ----------------------
422
423 Running the notebook makes the current python installation available as a kernel. Other
424 python installations (different python versions, virtualenv or conda environments) can
425 be installed as kernels by following these steps:
426
427 * make sure that the desired python installation is active (e.g. activate the environment)
428 and ipython is installed
429 * run once ``ipython kernelspec install-self --user`` (or ``ipython2 ...`` or ``ipython3 ...``
430 if you want to install specific python versions)
431
432 The last command installs a kernel spec file for the current python installation in
433 ``~/.ipython/kernels/``. Kernel spec files are JSON files, which can be viewed and changed with a
434 normal text editor.
435
436 Kernels for other languages can be found in the `IPython wiki
437 <https://github.com/ipython/ipython/wiki/IPython%20kernels%20for%20other%20languages>`_.
438 They usually come with instruction what to run to make the kernel available in the notebook.
439
420 440
421 441 .. _signing_notebooks:
422 442
423 443 Signing Notebooks
424 444 -----------------
425 445
426 446 To prevent untrusted code from executing on users' behalf when notebooks open,
427 447 we have added a signature to the notebook, stored in metadata.
428 448 The notebook server verifies this signature when a notebook is opened.
429 449 If the signature stored in the notebook metadata does not match,
430 450 javascript and HTML output will not be displayed on load,
431 451 and must be regenerated by re-executing the cells.
432 452
433 453 Any notebook that you have executed yourself *in its entirety* will be considered trusted,
434 454 and its HTML and javascript output will be displayed on load.
435 455
436 456 If you need to see HTML or Javascript output without re-executing,
437 457 you can explicitly trust notebooks, such as those shared with you,
438 458 or those that you have written yourself prior to IPython 2.0,
439 459 at the command-line with::
440 460
441 461 $ ipython trust mynotebook.ipynb [other notebooks.ipynb]
442 462
443 463 This just generates a new signature stored in each notebook.
444 464
445 465 You can generate a new notebook signing key with::
446 466
447 467 $ ipython trust --reset
448 468
449 469
450 470 Importing ``.py`` files
451 471 -----------------------
452 472
453 473 ``.py`` files will be imported as a notebook with
454 474 the same basename, but an ``.ipynb`` extension, located in the notebook
455 475 directory. The notebook created will have just one cell, which will contain
456 476 all the code in the ``.py`` file. You can later manually partition this into
457 477 individual cells using the ``Edit | Split Cell`` menu option, or the
458 478 :kbd:`Ctrl-m -` keyboard shortcut.
459 479
460 480 Note that ``.py`` scripts obtained from a notebook document using :doc:`nbconvert <nbconvert>`
461 481 maintain the structure of the notebook in comments. Reimporting such a
462 482 script back into a notebook will preserve this structure.
463 483
464 484 .. _note_about_roundtrip:
465 485
466 486 .. warning::
467 487
468 488 While in simple cases you can "roundtrip" a notebook to Python, edit the
469 489 Python file, and then import it back without loss of main content, this is
470 490 in general *not guaranteed to work*. First, there is extra metadata
471 491 saved in the notebook that may not be saved to the ``.py`` format. And as
472 492 the notebook format evolves in complexity, there will be attributes of the
473 493 notebook that will not survive a roundtrip through the Python form. You
474 494 should think of the Python format as a way to output a script version of a
475 495 notebook and the import capabilities as a way to load existing code to get
476 496 a notebook started. But the Python version is *not* an alternate notebook
477 497 format.
478 498
479 499 .. seealso::
480 500 :ref:`nbformat`
481 501
482 502 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now