##// END OF EJS Templates
nbconvert
David P. Sanders -
Show More
@@ -74,8 +74,8 b' how to install the notebook and its dependencies.'
74 option.
74 option.
75
75
76
76
77 Running the IPython Notebook web app
77 Starting up the IPython Notebook web app
78 ====================================
78 ----------------------------------------
79
79
80 The Notebook web app is started with the command::
80 The Notebook web app is started with the command::
81
81
@@ -148,24 +148,16 b' At certain moments, it may be necessary to interrupt a particularly long calcula'
148 After a restart, all relevant cells must be re-evaluated
148 After a restart, all relevant cells must be re-evaluated
149
149
150
150
151 Saveing a notebook
151 A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the menu option ``File -> Download as``
152 ------------------
152 Choosing the ``.py`` option removes all output and saves the text cells
153
154 The `Download` button lets you save a notebook file to the Download area
155 configured by your web browser (particularly useful if you are running the
156 notebook server on a remote host and need a file locally).
157 But you can always export
158 the input part of a notebook to a plain python script by choosing Python format
159 in the `Download` drop list. This removes all output and saves the text cells
160 in comment areas. See ref:`below <notebook_format>` for more details on the
153 in comment areas. See ref:`below <notebook_format>` for more details on the
161 notebook format.
154 notebook format.
162
155
163
156
164 .. warning::
157 .. warning::
165
158
166 While in simple cases you can roundtrip a notebook to Python, edit the
159 While in simple cases you can "roundtrip" a notebook to Python, edit the
167 python file and import it back without loss of main content, this is in
160 Python file, and then import it back without loss of main content, this is in general *not guaranteed to work*. First, there is extra metadata
168 general *not guaranteed to work at all*. First, there is extra metadata
169 saved in the notebook that may not be saved to the ``.py`` format. And as
161 saved in the notebook that may not be saved to the ``.py`` format. And as
170 the notebook format evolves in complexity, there will be attributes of the
162 the notebook format evolves in complexity, there will be attributes of the
171 notebook that will not survive a roundtrip through the Python form. You
163 notebook that will not survive a roundtrip through the Python form. You
@@ -174,49 +166,35 b' notebook format.'
174 notebook started. But the Python version is *not* an alternate notebook
166 notebook started. But the Python version is *not* an alternate notebook
175 format.
167 format.
176
168
177
178 Importing or executing a notebook as a normal Python file
179 ---------------------------------------------------------
180
181 The native format of the notebook, a file with a ``.ipynb`` `extension, is a
182 JSON container of all the input and output of the notebook, and therefore not
183 valid Python by itself. This means that by default, you cannot directly
184 import a notebook from Python, nor execute it as a normal python script.
185
169
186 But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
170 Keyboard shortcuts
187
171 ------------------
188 ipython notebook --script
172 All actions in the notebook can be achieved with the mouse, but we have also
189
173 added keyboard shortcuts for the most common ones, so that productive use of
190 or you can set this option permanently in your configuration file with::
174 the notebook can be achieved with minimal mouse intervention. The main
191
175 key bindings you need to remember are:
192 c.NotebookManager.save_script=True
193
194 This will instruct the notebook server to save the ``.py`` export of each
195 notebook, in addition to the ``.ipynb``, at every save. These are standard ``.py`` files, and so they can be
196 ``%run``, imported from regular IPython sessions or other notebooks, or
197 executed at the command-line. Since we export the raw
198 code you have typed, for these files to be importable from other code you will
199 have to avoid using syntax such as ``%magics`` and other IPython-specific
200 extensions to the language.
201
202 In regular practice, the standard way to differentiate importable code from the
203 'executable' part of a script is to put at the bottom::
204
176
205 if __name__ == '__main__':
177 * :kbd:`Shift-Enter`:
206 # rest of the code...
178 execute the current cell, show output (if any), and jump
179 to the next cell below. If :kbd:`Shift-Enter`
180 was invoked on the last input line, a new code cell will also be created. Note that in the notebook, simply using :kbd:`Enter` *never* forces execution, it simply inserts a new line in the current cell. Therefore, in the notebook you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and click on the ``Run Selected`` button).
207
181
208 Since all cells in the notebook are run as top-level code, you'll need to
182 * :kbd:`Alt-Enter`:
209 similarly protect *all* cells that you do not want executed when other scripts
183 this combination is similar to the previous one, with the
210 try to import your notebook. A convenient shortand for this is to define early
184 exception that, if the next cell below is not empty, a new code cell will be
211 on::
185 added to the notebook, even if the cell execution happens not in the last cell. :kbd:`Alt-Enter`: is a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
186
187 * :kbd:`Ctrl-Enter`:
188 execute the current cell in "terminal mode", where any
189 output is shown, but the cursor remains in the current cell. This is convenient to do quick in-place experiments, or query things like filesystem content, without creating additional cells that you may not want saved in your notebook.
212
190
213 script = __name__ == '__main__'
191 * :kbd:`Ctrl-m`:
192 this is the prefix for all other keybindings, which consist of an additional single letter or character. Type :kbd:`Ctrl-m h` (that is, the sole letter
193 :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining available keybindings.
214
194
215 and then on any cell that you need to protect, use::
216
195
217 if script:
218 # rest of the cell...
219
196
197
220
198
221 Cell types
199 Cell types
222 ----------
200 ----------
@@ -305,20 +283,44 b' When the default ``%matplotlib`` or ``%pylab`` magics are used, the output of a '
305 ``%matplotlib inline``
283 ``%matplotlib inline``
306 which captures the output inline within the notebook format. This has the benefit that the resulting plots will be stored in the notebook document.
284 which captures the output inline within the notebook format. This has the benefit that the resulting plots will be stored in the notebook document.
307
285
308 Converting notebooks to other formats using nbconvert
286
309 ------------------------------------------------------
287 Converting notebooks to other formats
288 -------------------------------------
289 Newly added in the 1.0 release of IPython is the ``nbconvert`` tool to convert a notebook document into another static format. This is a command line tool; at present, this functionality is not available to export directly from within the Notebook app. The syntax is::
290
291 ``$ ipython nbconvert notebook.ipynb``
292
293 for standard HTML output, or::
294
295 ``$ ipython nbconvert --format=FORMAT notebook.ipynb``
296
297 where ``FORMAT`` is the desired export format. Options for this format include:
298
299 * ``full_html``:
300 Standard HTML
301
302 * ``simple_html``:
303 A simplified version of HTML
304
305 * ``reveal``:
306 A format to be used with the ``reveal.js`` package for slideshow presentations.
307
308 * ``sphinx_howto``:
309 A standard documentation format.
310
311 * ``latex``:
312 Produces LaTeX output which may be compiled with ``pdflatex`` to PDF.
310
313
311
314
312 Configuration
315 Configuration
313 -------------
316 -------------
314
317 The IPython Notebook can be run with a variety of command line arguments.
315 The IPython notebook server can be run with a variety of command line arguments.
316 To see a list of available options enter::
318 To see a list of available options enter::
317
319
318 $ ipython notebook --help
320 $ ipython notebook --help
319
321
320 Defaults for these options can also be set by creating a file named
322 Defaults for these options can also be set by creating a file named
321 ``ipython_notebook_config.py`` in your IPython profile folder. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
323 ``ipython_notebook_config.py`` in your IPython *profile folder*. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
322
324
323 To create a new set of default configuration files, with lots of information on available options, use::
325 To create a new set of default configuration files, with lots of information on available options, use::
324
326
@@ -329,38 +331,47 b' To create a new set of default configuration files, with lots of information on '
329 :ref:`config_overview`, in particular :ref:`Profiles`.
331 :ref:`config_overview`, in particular :ref:`Profiles`.
330
332
331
333
332 Keyboard shortcuts
333 ------------------
334
334
335 All actions in the notebook can be achieved with the mouse, but we have also
335 Importing or executing a notebook as a normal Python file
336 added keyboard shortcuts for the most common ones, so that productive use of
336 ---------------------------------------------------------
337 the notebook can be achieved with minimal mouse intervention. The main
338 key bindings you need to remember are:
339
337
340 * :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console),
338 The native format of the notebook, a file with a ``.ipynb`` `extension, is a
341 show output (if any) and jump to the next cell below. If :kbd:`Shift-Enter`
339 JSON container of all the input and output of the notebook, and therefore not
342 was invoked on the last input line, a new code cell will also be created. Note
340 valid Python by itself. This means that by default, you cannot directly
343 that in the notebook, simply using :kbd:`Enter` *never* forces execution,
341 import a notebook from Python, nor execute it as a normal python script.
344 it simply inserts a new line in the current cell. Therefore, in the notebook
345 you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and
346 click on the ``Run Selected`` button).
347
342
348 * :kbd:`Alt-Enter`: this combination is similar to the previous one, with the
343 But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
349 exception that, if the next cell below is not empty, a new code cell will be
344
350 added to the notebook, even if the cell execution happens not in the last cell.
345 ipython notebook --script
351 In this regard, :kbd:`Alt-Enter`: is simply a shortcut for the :kbd:`Shift-Enter`,
346
352 :kbd:`Ctrl-m a` sequence.
347 or you can set this option permanently in your configuration file with::
353
348
354 * :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any
349 c.NotebookManager.save_script=True
355 output is shown but the cursor stays in the current cell, whose input
350
356 area is flushed empty. This is convenient to do quick in-place experiments
351 This will instruct the notebook server to save the ``.py`` export of each
357 or query things like filesystem content without creating additional cells you
352 notebook, in addition to the ``.ipynb``, at every save. These are standard
358 may not want saved in your notebook.
353 ``.py`` files, and so they can be ``%run``, imported from regular IPython
359
354 sessions or other notebooks, or executed at the command line. Since we export
360 * :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist
355 the raw code you have typed, for these files to be importable from other code,
361 of an additional single letter. Type :kbd:`Ctrl-m h` (that is, the sole
356 you will have to avoid using syntax such as ``%magic``s and other IPython-specific extensions to the language.
362 letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining
357
363 available keybindings.
358 In regular practice, the standard way to differentiate importable code from the
359 'executable' part of a script is to put at the bottom::
360
361 if __name__ == '__main__':
362 # rest of the code...
363
364 Since all cells in the notebook are run as top-level code, you will need to
365 similarly protect *all* cells that you do not want executed when other scripts
366 try to import your notebook. A convenient shortand for this is to define early
367 on::
368
369 script = __name__ == '__main__'
370
371 and then on any cell that you need to protect, use::
372
373 if script:
374 # rest of the cell...
364
375
365
376
366 .. _notebook_security:
377 .. _notebook_security:
General Comments 0
You need to be logged in to leave comments. Login now