##// END OF EJS Templates
Merge pull request #3958 from ivanov/doc-nomenclature...
Min RK -
r12099:c2b47c8f merge
parent child Browse files
Show More
@@ -0,0 +1,9 b''
1 <html>
2 <head>
3 <meta http-equiv="Refresh" content="0; url=notebook.html" />
4 <title>Notebook page has move</title>
5 </head>
6 <body>
7 <p>The notebook page has moved to <a href="notebook.html">this link</a>.</p>
8 </body>
9 </html>
@@ -157,7 +157,9 b" html_last_updated_fmt = '%b %d, %Y'"
157 157
158 158 # Additional templates that should be rendered to pages, maps page names to
159 159 # template names.
160 #html_additional_pages = {}
160 html_additional_pages = {
161 'interactive/htmlnotebook': 'htmlnotebook.html',
162 }
161 163
162 164 # If false, no module index is generated.
163 165 #html_use_modindex = True
@@ -342,7 +342,7 b' Dependencies for the IPython HTML notebook'
342 342 ==========================================
343 343
344 344 The IPython notebook is a notebook-style web interface to IPython and can be
345 started withe command ``ipython notebook``.
345 started with the command ``ipython notebook``.
346 346
347 347 pyzmq
348 348 -----
@@ -12,6 +12,6 b' Using IPython for interactive work'
12 12 qtconsole
13 13 notebook
14 14 nbconvert
15 working_remotely
15 public_server
16 16
17 17
@@ -67,7 +67,7 b' The currently supported export formats are:'
67 67 * ``--to markdown``
68 68
69 69 Simple markdown output. Markdown cells are unaffected,
70 and code cells are placed in triple-backtick (``\`\`\```) blocks.
70 and code cells are placed in triple-backtick (```````) blocks.
71 71
72 72 * ``--to rst``
73 73
This diff has been collapsed as it changes many lines, (571 lines changed) Show them Hide them
@@ -3,261 +3,240 b''
3 3 The IPython Notebook
4 4 ====================
5 5
6 The IPython Notebook is part of the IPython package, which aims to provide a
7 powerful, interactive approach to scientific computation.
8 The IPython Notebook extends the previous text-console-based approach, and the
9 later Qt console, in a qualitatively new diretion, providing a web-based
10 application suitable for capturing the whole scientific computation process.
11
12 .. seealso::
13
14 :ref:`Installation requirements <installnotebook>` for the Notebook.
15
16
17 .. Basic structure
18 .. ---------------
19
20 6 Introduction
21 7 ------------
22 8
23 The IPython Notebook combines two components:
24
25 * **The IPython Notebook web application**:
26
27 The *IPython Notebook web app* is a browser-based tool for interactive
28 authoring of literate computations, in which explanatory text,
29 mathematics, computations and rich media output may be combined. Input
30 and output are stored in persistent cells that may be edited in-place.
9 The notebook extends the console-based approach to interactive computing in
10 a qualitatively new direction, providing a web-based application suitable for
11 capturing the whole computation process: developing, documenting, and
12 executing code, as well as communicating the results. The IPython notebook
13 combines two components:
31 14
32 * **Notebook documents**:
15 **A web application**: a browser-based tool for interactive authoring of
16 documents which combine explanatory text, mathematics, computations and their
17 rich media output.
33 18
34 *Notebook documents*, or *notebooks*, are plain text documents which
35 record all inputs and outputs of the computations, interspersed with
36 text, mathematics and HTML 5 representations of objects, in a literate
37 style.
19 **Notebook documents**: a representation of all content visible in the web
20 application, including inputs and outputs of the computations, explanatory
21 text, mathematics, images, and rich media representations of objects.
38 22
39 Since the similarity in names can lead to some confusion, in this
40 documentation we will use capitalization of the word "notebook" to
41 distinguish the Notebook app and notebook documents, thinking of the
42 Notebook app as being a proper noun. We will also always refer to the
43 "Notebook app" when we are referring to the browser-based interface,
44 and usually to "notebook documents", instead of "notebooks", for added
45 precision.
23 .. seealso::
46 24
47 We refer to the current state of the computational process taking place in the
48 Notebook app, i.e. the (numbered) sequence of input and output cells, as the
49 *notebook space*. Notebook documents provide an *exact*, *one-to-one* record
50 of all the content in the notebook space, as a plain text file in JSON format.
51 The Notebook app automatically saves, at certain intervals, the contents of
52 the notebook space to a notebook document stored on disk, with the same name
53 as the title of the notebook space, and the file extension ``.ipynb``. For
54 this reason, there is no confusion about using the same word "notebook" for
55 both the notebook space and the corresponding notebook document, since they are
56 really one and the same concept (we could say that they are "isomorphic").
25 See the :ref:`installation documentation <installnotebook>` for directions
26 on how to install the notebook and its dependencies.
57 27
58 28
59 Main features of the IPython Notebook web app
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29 Main features of the web application
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61 31
62 The main features of the IPython Notebook app include:
32 * In-browser editing for code, with automatic syntax highlighting,
33 indentation, and tab completion/introspection.
63 34
64 * In-browser editing for code, with automatic syntax highlighting and
65 indentation and tab completion/introspection.
35 * The ability to execute code from the browser, with the results of
36 computations attached to the code which generated them.
66 37
67 * Literate combination of code with rich text using the Markdown_ markup
68 language.
38 * Displaying the result of computation using rich media representations, such
39 as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
40 rendered by the matplotlib_ library, can be included inline.
69 41
70 * Mathematics is easily included within the Markdown using LaTeX notation, and
71 rendered natively by MathJax_.
42 * In-browser editing for rich text using the Markdown_ markup language, which
43 can provide commentary for the code, is not limited to plain text.
72 44
73 * Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result
74 of computations.
45 * The ability to easily include mathematical notation within markdown cells
46 using LaTeX, and rendered natively by MathJax_.
75 47
76 * Publication-quality figures in a range of formats (SVG / PNG), rendered by
77 the matplotlib_ library, may be included inline and exported.
78 48
79 49
80 50 .. _MathJax: http://www.mathjax.org/
81 .. _matplotlib: http://matplotlib.org/
82 .. _Markdown: http://daringfireball.net/projects/markdown/syntax
83 51
84 52
85 53 Notebook documents
86 54 ~~~~~~~~~~~~~~~~~~
87
88 Notebook document files are simple JSON_ files with the
89 extension ``.ipynb``.
90 Since JSON is just plain text, they can be easily version-controlled and shared with colleagues.
91 The notebook stores a *complete*, *reproducible*, *one-to-one* copy of the state of the
92 computational state as it is inside the Notebook app. All computations
93 carried out, and the corresponding results obtained, can be combined in
94 a literate way, interleaving executable code with rich text, mathematics,
95 and rich representations of objects.
96
55 Notebook documents contains the inputs and outputs of a interactive session as
56 well as additional text that accompanies the code but is not meant for
57 execution. In this way, notebook files can serve as a complete computational
58 record of a session, interleaving executable code with explanatory text,
59 mathematics, and rich representations of resulting objects. These documents
60 are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
61 JSON is a plain text format, they can be version-controlled and shared with
62 colleagues.
63
97 64 .. _JSON: http://en.wikipedia.org/wiki/JSON
98 65
99 Notebooks may easily be exported to a range of static formats, including
100 HTML (for example, for blog posts), PDF and slide shows,
101 via the new nbconvert_ command.
66 Notebooks may be exported to a range of static formats, including HTML (for
67 example, for blog posts), reStructeredText, LaTeX, PDF, and slide shows, via
68 the new :ref:`nbconvert <nbconvert>` command.
102 69
103 70 Furthermore, any ``.ipynb`` notebook document available from a public
104 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ service.
105 This service loads the notebook document from the URL and will
106 render it as a static web page. The results may thus be shared with a
107 colleague, or as a public blog post, without other users needing to install
108 IPython themselves. NbViewer is simply NbConvert as a simple heroku webservice.
71 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
72 This service loads the notebook document from the URL and renders it as a
73 static web page. The results may thus be shared with a colleague, or as a
74 public blog post, without other users needing to install IPython themselves.
75 In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
76 so you can do your own static conversions with nbconvert, without relying on
77 nbviewer.
109 78
110 See the :ref:`installation documentation <install_index>` for directions on
111 how to install the notebook and its dependencies.
112 79
113 .. _nbviewer: http://nbviewer.ipython.org
114 80
115 .. note::
81 .. seealso::
116 82
117 You can start more than one notebook server at the same time, if you want
118 to work on notebooks in different directories. By default the first
119 notebook server starts on port 8888, and later notebook servers search for
120 ports near that one. You can also manually specify the port with the
121 ``--port`` option.
83 :ref:`Details on the notebook JSON file format <notebook_format>`
122 84
123 85
124 Basic workflow in the IPython Notebook web app
125 ----------------------------------------------
86 Starting the notebook server
87 ----------------------------
126 88
127 Starting up
128 ~~~~~~~~~~~~
89 You can start running a notebook server from the command line using the
90 following command::
129 91
130 You can start running the Notebook web app using the following command::
92 ipython notebook
131 93
132 $ ipython notebook
94 This will print some information about the notebook server in your console,
95 and open a web browser to the URL of the web application (by default,
96 ``http://127.0.0.1:8888``).
133 97
134 (Here, and in the sequel, the initial ``$`` represents the shell prompt,
135 indicating that the command is to be run from the command line in a shell.)
98 The landing page of the IPython notebook web application, the **dashboard**,
99 shows the notebooks currently available in the notebook directory (by default,
100 the directory from which the notebook server was started).
136 101
137 The landing page of the IPython Notebook application, the *dashboard*, shows
138 the notebooks currently available in the *notebook directory* (By default, the directory
139 from which the notebook was started).
140 102 You can create new notebooks from the dashboard with the ``New Notebook``
141 button, or open existing ones by clicking on their name.
142 You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python
143 source code files into the notebook list area.
103 button, or open existing ones by clicking on their name. You can also drag
104 and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
105 into the notebook list area.
144 106
107 When starting a notebook server from the command line, you can also open a
108 particular notebook directly, bypassing the dashboard, with ``ipython notebook
109 my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
110 given.
145 111
146 You can open an existing notebook directly, without having to go via the
147 dashboard, with:
112 When you are inside an open notebook, the `File | Open...` menu option will
113 open the dashboard in a new browser tab, to allow you to open another notebook
114 from the notebook directory or to create a new notebook.
148 115
149 ipython notebook my_notebook
150 116
151 The `.ipynb` extension is assumed if no extension is given.
117 .. note::
152 118
153 The `File | Open...` menu option will open the dashboard in a new browser tab,
154 to allow you to select a current notebook
155 from the notebook directory or to create a new notebook.
119 You can start more than one notebook server at the same time, if you want
120 to work on notebooks in different directories. By default the first
121 notebook server starts on port 8888, and later notebook servers search for
122 ports near that one. You can also manually specify the port with the
123 ``--port`` option.
124
125 Creating a new notebook document
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156 127
128 A new notebook may be created at any time, either from the dashboard, or using
129 the `File | New` menu option from within an active notebook. The new notebook
130 is created within the same directory and will open in a new browser tab. It
131 will also be reflected as a new entry in the notebook list on the dashboard.
157 132
158 133
159 Notebook user interface
160 ~~~~~~~~~~~~~~~~~~~~~~~
134 Opening notebooks
135 ~~~~~~~~~~~~~~~~~
136 An open notebook has **exactly one** interactive session connected to an
137 :ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
138 and communicate back results. This kernel remains active if the web browser
139 window is closed, and reopening the same notebook from the dashboard will
140 reconnect the web application to the same kernel. In the dashboard, notebooks
141 with an active kernel have a ``Shutdown`` button next to them, whereas
142 notebooks without an active kernel have a ``Delete`` button in its place.
161 143
162 When you open a new notebook document in the Notebook, you will be presented
163 with the title associated to the notebook space/document, a *menu bar*, a
164 *toolbar* and an empty *input cell*.
144 Other clients may connect to the same underlying IPython kernel.
145 The notebook server always prints to the terminal the full details of
146 how to connect to each kernel, with messages such as the following::
165 147
166 Notebook title
167 ^^^^^^^^^^^^^^
168 The title of the notebook document that is currently being edited is displayed
169 at the top of the page, next to the ``IP[y]: Notebook`` logo. This title may
170 be edited directly by clicking on it. The title is reflected in the name of
171 the ``.ipynb`` notebook document file that is saved.
148 [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
172 149
173 Menu bar
174 ^^^^^^^^
175 The menu bar presents different options that may be used to manipulate the way
176 the Notebook functions.
150 This long string is the kernel's ID which is sufficient for getting the
151 information necessary to connect to the kernel. You can also request this
152 connection data by running the ``%connect_info`` :ref:`magic
153 <magics_explained>`. This will print the same ID information as well as the
154 content of the JSON data structure it contains.
177 155
178 Toolbar
179 ^^^^^^^
180 The tool bar gives a quick way of accessing the most-used operations within
181 the Notebook, by clicking on an icon.
156 You can then, for example, manually start a Qt console connected to the *same*
157 kernel from the command line, by passing a portion of the ID::
182 158
159 $ ipython qtconsole --existing 87f7d2c0
183 160
184 Creating a new notebook document
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161 Without an ID, ``--existing`` will connect to the most recently
162 started kernel. This can also be done by running the ``%qtconsole``
163 :ref:`magic <magics_explained>` in the notebook.
186 164
187 A new notebook space/document may be created at any time, either from the
188 dashboard, or using the `File | New` menu option from within an active
189 notebook. The new notebook is created within the same directory and
190 will open in a new browser tab. It will also be reflected as a new entry in
191 the notebook list on the dashboard.
165 .. seealso::
192 166
167 :ref:`ipythonzmq`
193 168
194 Structure of a notebook document
195 --------------------------------
169 Notebook user interface
170 -----------------------
196 171
197 Input cells
198 ~~~~~~~~~~~
199 Input cells are at the core of the functionality of the IPython Notebook.
200 They are regions in the document in which you can enter different types of
201 text and commands. To *execute* or *run* the *current cell*, i.e. the cell
202 under the cursor, you can use the :kbd:`Shift-Enter` key combination.
203 This tells the Notebook app to perform the relevant operation for each type of
204 cell (see below), and then to display the resulting output.
172 When you create a new notebook document, you will be presented with the
173 **notebook name**, a **menu bar**, a **toolbar** and an empty **code
174 cell**.
205 175
206 The notebook consists of a sequence of input cells, labelled ``In[n]``, which
207 may be executed in a non-linear way, and outputs ``Out[n]``, where ``n`` is a
208 number which denotes the order in which the cells were executed over the
209 history of the computational process. The contents of all of these cells are
210 accessible as Python variables with the same names, forming a complete record
211 of the history of the computation.
176 **notebook name**: The name of the notebook document is displayed at the top
177 of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
178 of the ``.ipynb`` notebook document file. Clicking on the notebook name
179 brings up a dialog which allows you to rename it. Thus, renaming a notebook
180 from "Untitled0" to "My first notebook" in the browser, renames the
181 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
212 182
183 **menu bar**: The menu bar presents different options that may be used to
184 manipulate the way the notebook functions.
213 185
186 **toolbar**: The tool bar gives a quick way of performing the most-used
187 operations within the notebook, by clicking on an icon.
214 188
215 Input cell types
216 ~~~~~~~~~~~~~~~~
217 Each IPython input cell has a *cell type*, of which there is a restricted
218 number. The type of a cell may be set by using the cell type dropdown on the
219 toolbar, or via the following keyboard shortcuts:
189 **code cell**: the default type of cell, read on for an explanation of cells
220 190
221 * **code**: :kbd:`Ctrl-m y`
222 * **markdown**: :kbd:`Ctrl-m m`
223 * **raw**: :kbd:`Ctrl-m t`
224 * **heading**: :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
225 191
226 Upon initial creation, each input cell is by default a code cell.
192 Structure of a notebook document
193 --------------------------------
194
195 The notebook consists of a sequence of cells. A cell is a multi-line
196 text input field, and its contents can be executed by using
197 :kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
198 `Cell | Run` in the menu bar. The execution behavior of a cell is determined
199 the cell's type. There are four types of cells: **code cells**, **markdown
200 cells**, **raw cells** and **heading cells**. Every cell starts off
201 being a **code cell**, but its type can be changed by using a dropdown on the
202 toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
203 <keyboard-shortcuts>`.
227 204
228 205
229 206 Code cells
230 ^^^^^^^^^^
231 A *code input cell* allows you to edit code inline within the cell, with full
232 syntax highlighting and autocompletion/introspection. By default, the language
233 associated to a code cell is Python, but other languages, such as ``julia``
234 and ``R``, can be handled using magic commands (see below).
235
236 When a code cell is executed with :kbd:`Shift-Enter`, the code that it
237 contains is transparently exported and run in that language (with automatic
238 compiling, etc., if necessary). The result that is returned from this
239 computation is then displayed in the notebook space as the cell's
240 *output*. If this output is of a textual nature, it is placed into a
241 numbered *output cell*. However, many other possible forms of output are also
242 possible, including ``matplotlib`` figures and HTML tables (as used, for
243 example, in the ``pandas`` data analyis package). This is known as IPython's
207 ~~~~~~~~~~
208 A *code cell* allows you to edit and write new code, with full syntax
209 highlighting and tab completion. By default, the language associated to a code
210 cell is Python, but other languages, such as ``Julia`` and ``R``, can be
211 handled using :ref:`cell magic commands <magics_explained>`.
212
213 When a code cell is executed, code that it contains is sent to the kernel
214 associated with the notebook. The results that are returned from this
215 computation are then displayed in the notebook as the cell's *output*. The
216 output is not limited to text, with many other possible forms of output are
217 also possible, including ``matplotlib`` figures and HTML tables (as used, for
218 example, in the ``pandas`` data analysis package). This is known as IPython's
244 219 *rich display* capability.
245 220
221 .. seealso::
222
223 `Basic Output`_ example notebook
224
225 `Rich Display System`_ example notebook
246 226
247 227 Markdown cells
248 ^^^^^^^^^^^^^^
228 ~~~~~~~~~~~~~~
249 229 You can document the computational process in a literate way, alternating
250 230 descriptive text with code, using *rich text*. In IPython this is accomplished
251 231 by marking up text with the Markdown language. The corresponding cells are
252 called *Markdown input cells*. The Markdown language provides a simple way to
232 called *Markdown cells*. The Markdown language provides a simple way to
253 233 perform this text markup, that is, to specify which parts of the text should
254 234 be emphasized (italics), bold, form lists, etc.
255 235
256 236
257 When a Markdown input cell is executed, the Markdown code is converted into
258 the corresponding formatted rich text. This output then *replaces* the
259 original Markdown input cell, leaving just the visually-significant marked up
260 rich text. Markdown allows arbitrary HTML code for formatting.
237 When a Markdown cell is executed, the Markdown code is converted into
238 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
239 formatting.
261 240
262 241 Within Markdown cells, you can also include *mathematics* in a straightforward
263 242 way, using standard LaTeX notation: ``$...$`` for inline mathematics and
@@ -274,17 +253,21 b' Standard mathematics environments defined by LaTeX and AMS-LaTeX (the'
274 253 New LaTeX macros may be defined using standard methods,
275 254 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
276 255 a Markdown cell. These definitions are then available throughout the rest of
277 the IPython session. (Note, however, that more care must be taken when using
278 nbconvert_ to output to LaTeX).
256 the IPython session.
279 257
280 Raw input cells
281 ~~~~~~~~~~~~~~~
258 .. seealso::
282 259
283 *Raw* input cells provide a place in which you can write *output* directly.
284 Raw cells are not evaluated by the Notebook, and have no output.
285 When passed through nbconvert, Raw cells arrive in the destination format unmodified,
286 allowing you to type full latex into a raw cell, which will only be rendered
287 by latex after conversion by nbconvert.
260 `Markdown Cells`_ example notebook
261
262 Raw cells
263 ~~~~~~~~~
264
265 *Raw* cells provide a place in which you can write *output* directly.
266 Raw cells are not evaluated by the notebook.
267 When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
268 destination format unmodified. For example, this allows you to type full LaTeX
269 into a raw cell, which will only be rendered by LaTeX after conversion by
270 nbconvert.
288 271
289 272 Heading cells
290 273 ~~~~~~~~~~~~~
@@ -292,10 +275,9 b' Heading cells'
292 275 You can provide a conceptual structure for your computational document as a
293 276 whole using different levels of headings; there are 6 levels available, from
294 277 level 1 (top level) down to level 6 (paragraph). These can be used later for
295 constructing tables of contents, etc.
296
297 As with Markdown cells, a heading input cell is replaced by a rich text
298 rendering of the heading when the cell is executed.
278 constructing tables of contents, etc. As with Markdown cells, a heading
279 cell is replaced by a rich text rendering of the heading when the cell is
280 executed.
299 281
300 282
301 283 Basic workflow
@@ -304,50 +286,36 b' Basic workflow'
304 286 The normal workflow in a notebook is, then, quite similar to a standard
305 287 IPython session, with the difference that you can edit cells in-place multiple
306 288 times until you obtain the desired results, rather than having to
307 rerun separate scripts with the ``%run`` magic command. (Magic commands do,
308 however, also work in the notebook; see below).
289 rerun separate scripts with the ``%run`` magic command.
290
309 291
310 292 Typically, you will work on a computational problem in pieces, organizing
311 293 related ideas into cells and moving forward once previous parts work
312 294 correctly. This is much more convenient for interactive exploration than
313 295 breaking up a computation into scripts that must be executed together, as was
314 previously necessary, especially if parts of them take a long time to run
315
316 The only significant limitation that the Notebook currently has, compared to
317 the Qt console, is that it cannot run any code that expects input from the
318 kernel (such as scripts that call :func:`raw_input`). Very importantly, this
319 means that the ``%debug`` magic does *not* currently work in the notebook!
320
321 This limitation will be overcome in the future, but in the meantime, there is
322 a simple solution for debugging: you can attach a Qt console to your existing
323 notebook kernel, and run ``%debug`` from the Qt console.
324 If your notebook is running on a local computer (i.e. if you are accessing it
325 via your localhost address at ``127.0.0.1``), then you can just type
326 ``%qtconsole`` in the notebook and a Qt console will open up, connected to
327 that same kernel.
296 previously necessary, especially if parts of them take a long time to run.
328 297
329 298 At certain moments, it may be necessary to interrupt a calculation which is
330 taking too long to complete. This may be done with the ``Kernel | Interrupt``
331 menu option, or the :kbd:``Ctrl-i`` keyboard shortcut.
299 taking too long to complete. This may be done with the `Kernel | Interrupt`
300 menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
332 301 Similarly, it may be necessary or desirable to restart the whole computational
333 process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.``
334 shortcut. This gives an equivalent state to loading the notebook document
335 afresh.
302 process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
303 shortcut.
336 304
337
338 .. warning::
305 A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
306 menu option `File | Download as`. Choosing the ``.py`` option downloads a
307 Python ``.py`` script, in which all rich output has been removed and the
308 content of markdown cells have been inserted as comments.
339 309
340 While in simple cases you can "roundtrip" a notebook to Python, edit the
341 Python file, and then import it back without loss of main content, this is
342 in general *not guaranteed to work*. First, there is extra metadata
343 saved in the notebook that may not be saved to the ``.py`` format. And as
344 the notebook format evolves in complexity, there will be attributes of the
345 notebook that will not survive a roundtrip through the Python form. You
346 should think of the Python format as a way to output a script version of a
347 notebook and the import capabilities as a way to load existing code to get
348 a notebook started. But the Python version is *not* an alternate notebook
349 format.
310 .. seealso::
311
312 `Running Code in the IPython Notebook`_ example notebook
313
314 `Basic Output`_ example notebook
315
316 :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
350 317
318 .. _keyboard-shortcuts:
351 319
352 320 Keyboard shortcuts
353 321 ~~~~~~~~~~~~~~~~~~
@@ -357,10 +325,10 b' to remember are the following:'
357 325
358 326 * :kbd:`Shift-Enter`: run cell
359 327 Execute the current cell, show output (if any), and jump to the next cell
360 below. If :kbd:`Shift-Enter` is invoked on the last input cell, a new code
328 below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
361 329 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
362 330 on its own *never* forces execution, but rather just inserts a new line in
363 the current input cell. :kbd:`Shift-Enter` is equivalent to clicking the
331 the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
364 332 ``Cell | Run`` menu item.
365 333
366 334 * :kbd:`Ctrl-Enter`: run cell in-place
@@ -373,7 +341,7 b' to remember are the following:'
373 341 to be saved in the notebook.
374 342
375 343 * :kbd:`Alt-Enter`: run cell, insert below
376 Executes the current cell, shows the output, and inserts a *new* input
344 Executes the current cell, shows the output, and inserts a *new*
377 345 cell between the current cell and the cell below (if one exists). This
378 346 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
379 347 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
@@ -425,96 +393,19 b' Ctrl-m h show keyboard shortcuts'
425 393
426 394
427 395
428 Magic commands
429 --------------
430 Magic commands, or *magics*, are commands for controlling IPython itself.
431 They all begin with ``%`` and are entered into code input cells; the code
432 cells are executed as usual with :kbd:`Shift-Enter`.
433
434 The magic commands call special functions defined by IPython which manipulate
435 the computational state in certain ways.
436
437 There are two types of magics:
438
439 - **line magics**:
440
441 These begin with a single ``%`` and take as arguments the rest of the
442 *same line* of the code cell. Any other lines of the code cell are
443 treated as if they were part of a standard code cell.
444
445 - **cell magics**:
446
447 These begin with ``%%`` and operate on the *entire* remaining contents
448 of the code cell.
449
450 Line magics
451 ~~~~~~~~~~~
452 Some of the available line magics are the following:
453
454 * ``%load filename``:
455
456 Loads the contents of the file ``filename`` into a new code cell. This
457 can be a URL for a remote file.
458
459 * ``%timeit code``:
460
461 An easy way to time how long the single line of code ``code`` takes to
462 run
463
464 * ``%config``:
465
466 Configuration of the IPython Notebook
467
468 * ``%lsmagic``:
469
470 Provides a list of all available magic commands
471
472 Cell magics
473 ~~~~~~~~~~~
474
475 * ``%%latex``:
476
477 Renders the entire contents of the cell in LaTeX, without needing to use
478 explicit LaTeX delimiters.
479
480 * ``%%bash``:
481
482 The code cell is executed by sending it to be executed by ``bash``. The
483 output of the ``bash`` commands is captured and displayed in the
484 notebook.
485
486 * ``%%file filename``:
487
488 Writes the contents of the cell to the file ``filename``.
489 **Caution**: The file is over-written without warning!
490
491 * ``%%R``:
492
493 Execute the contents of the cell using the R language.
494
495 * ``%%timeit``:
496
497 Version of ``%timeit`` which times the entire block of code in the
498 current code cell.
499
500
501
502 Several of the cell magics provide functionality to manipulate the filesystem
503 of a remote server to which you otherwise do not have access.
504 396
505 397
506 398 Plotting
507 399 --------
508 One major feature of the Notebook is the ability to interact with
509 plots that are the output of running code cells. IPython is designed to work
510 seamlessly with the ``matplotlib`` plotting library to provide this
511 functionality.
400 One major feature of the notebook is the ability to display plots that are the
401 output of running code cells. IPython is designed to work seamlessly with the
402 matplotlib_ plotting library to provide this functionality.
512 403
513 404 To set this up, before any plotting is performed you must execute the
514 ``%matplotlib`` magic command. This performs the necessary behind-the-scenes
515 setup for IPython to work correctly hand in hand with ``matplotlib``; it does
516 *not*, however, actually execute any Python ``import`` commands, that is, no
517 names are added to the namespace.
405 ``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
406 necessary behind-the-scenes setup for IPython to work correctly hand in hand
407 with ``matplotlib``; it does *not*, however, actually execute any Python
408 ``import`` commands, that is, no names are added to the namespace.
518 409
519 410 If the ``%matplotlib`` magic is called without an argument, the
520 411 output of a plotting command is displayed using the default ``matplotlib``
@@ -523,25 +414,24 b' requested using, for example::'
523 414
524 415 %matplotlib gtk
525 416
526 A particularly interesting backend is the ``inline`` backend.
527 This is applicable only for the IPython Notebook and the IPython QtConsole.
528 It can be invoked as follows::
417 A particularly interesting backend, provided by IPython, is the ``inline``
418 backend. This is available only for the IPython Notebook and the
419 :ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
529 420
530 421 %matplotlib inline
531 422
532 With this backend, output of plotting commands is displayed *inline* within
533 the notebook format, directly below the input cell that produced it. The
534 resulting plots will then also be stored in the notebook document. This
535 provides a key part of the functionality for reproducibility_ that the IPython
536 Notebook provides.
423 With this backend, the output of plotting commands is displayed *inline*
424 within the notebook, directly below the code cell that produced it. The
425 resulting plots will then also be stored in the notebook document.
537 426
538 .. _reproducibility: https://en.wikipedia.org/wiki/Reproducibility
427 .. seealso::
539 428
429 `Plotting with Matplotlib`_ example notebook
540 430
541 431
542 432 Configuring the IPython Notebook
543 433 --------------------------------
544 The IPython Notebook can be run with a variety of command line arguments.
434 The notebook server can be run with a variety of command line arguments.
545 435 To see a list of available options enter::
546 436
547 437 $ ipython notebook --help
@@ -558,24 +448,45 b' on available options, use::'
558 448
559 449 $ ipython profile create
560 450
561 .. seealso:
451 .. seealso::
562 452
563 453 :ref:`config_overview`, in particular :ref:`Profiles`.
454
455 :ref:`notebook_security`
564 456
457 :ref:`notebook_public_server`
565 458
566 Importing `.py` files
567 ----------------------
568 459
460 Importing ``.py`` files
461 -----------------------
569 462
570 ``.py`` files will be imported into the IPython Notebook as a notebook with
463 ``.py`` files will be imported as a notebook with
571 464 the same basename, but an ``.ipynb`` extension, located in the notebook
572 465 directory. The notebook created will have just one cell, which will contain
573 466 all the code in the ``.py`` file. You can later manually partition this into
574 467 individual cells using the ``Edit | Split Cell`` menu option, or the
575 468 :kbd:`Ctrl-m -` keyboard shortcut.
576 469
577 .. Alternatively, prior to importing the ``.py``, you can manually add ``# <
578 nbformat>2</nbformat>`` at the start of the file, and then add separators for
579 text and code cells, to get a cleaner import with the file already broken into
580 individual cells.
470 Note that ``.py`` scripts obtained from a notebook document using nbconvert_
471 maintain the structure of the notebook in comments. Reimporting such a
472 script back into a notebook will preserve this structure.
473
474 .. _note_about_roundtrip:
475
476 .. warning::
477
478 While in simple cases you can "roundtrip" a notebook to Python, edit the
479 Python file, and then import it back without loss of main content, this is
480 in general *not guaranteed to work*. First, there is extra metadata
481 saved in the notebook that may not be saved to the ``.py`` format. And as
482 the notebook format evolves in complexity, there will be attributes of the
483 notebook that will not survive a roundtrip through the Python form. You
484 should think of the Python format as a way to output a script version of a
485 notebook and the import capabilities as a way to load existing code to get
486 a notebook started. But the Python version is *not* an alternate notebook
487 format.
488
489 .. seealso::
490 :ref:`notebook_format`
581 491
492 .. include:: ../links.txt
@@ -1,20 +1,28 b''
1 1 .. _working_remotely.txt
2 2
3 Working remotely
4 ================
3 Running a notebook server
4 =========================
5 5
6 6
7 The IPython Notebook web app is based on a server-client structure.
8 This server uses a two-process kernel architecture based on ZeroMQ, as well as
9 Tornado for serving HTTP requests. Other clients may connect to the same
10 underlying IPython kernel; see below.
7 The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
8 server-client structure. This server uses a :ref:`two-process kernel
9 architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
10 HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
11 and is accessible only from `localhost`. This document describes how you can
12 :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
13 a public interface <notebook_public_server>`.
14
15 .. _ZeroMQ: http://zeromq.org
16
17 .. _Tornado: http://www.tornadoweb.org
18
11 19
12 20 .. _notebook_security:
13 21
14 Security
15 --------
22 Notebook security
23 -----------------
16 24
17 You can protect your Notebook server with a simple single password by
25 You can protect your notebook server with a simple single password by
18 26 setting the :attr:`NotebookApp.password` configurable. You can prepare a
19 27 hashed password using the function :func:`IPython.lib.security.passwd`:
20 28
@@ -58,10 +66,9 b' the command::'
58 66 Your browser will warn you of a dangerous certificate because it is
59 67 self-signed. If you want to have a fully compliant certificate that will not
60 68 raise warnings, it is possible (but rather involved) to obtain one,
61 `as explained in detailed in this tutorial`__.
69 as explained in detail in `this tutorial`__.
62 70
63 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-
64 secure-sertificate-for-free.ars
71 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
65 72
66 73 Keep in mind that when you enable SSL support, you will need to access the
67 74 notebook server over ``https://``, not over plain ``http://``. The startup
@@ -69,32 +76,7 b' message from the server prints this, but it is easy to overlook and think the'
69 76 server is for some reason non-responsive.
70 77
71 78
72 Connecting to an existing kernel
73 ---------------------------------
74
75 The notebook server always prints to the terminal the full details of
76 how to connect to each kernel, with messages such as the following::
77
78 [IPKernelApp] To connect another client to this kernel, use:
79 [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
80
81 This long string is the name of a JSON file that contains all the port and
82 validation information necessary to connect to the kernel. You can then, for
83 example, manually start a Qt console connected to the *same* kernel with::
84
85 $ ipython qtconsole --existing
86 kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
87
88 If you have only a single kernel running, simply typing::
89
90 $ ipython qtconsole --existing
91
92 will automatically find it. (It will always find the most recently
93 started kernel if there is more than one.) You can also request this
94 connection data by typing ``%connect_info``; this will print the same
95 file information as well as the content of the JSON data structure it
96 contains.
97
79 .. _notebook_public_server:
98 80
99 81 Running a public notebook server
100 82 --------------------------------
@@ -147,8 +129,8 b' modifying ``ipython_notebook_config.py``)::'
147 129 Using a different notebook store
148 130 --------------------------------
149 131
150 By default, the Notebook app stores the notebook documents that it saves as
151 files in the working directory of the Notebook app, also known as the
132 By default, the notebook server stores the notebook documents that it saves as
133 files in the working directory of the notebook server, also known as the
152 134 ``notebook_dir``. This logic is implemented in the
153 135 :class:`FileNotebookManager` class. However, the server can be configured to
154 136 use a different notebook manager class, which can
@@ -173,9 +155,9 b' Known issues'
173 155 ------------
174 156
175 157 When behind a proxy, especially if your system or browser is set to autodetect
176 the proxy, the Notebook app might fail to connect to the server's websockets,
177 and present you with a warning at startup. In this case, you need to configure
178 your system not to use the proxy for the server's address.
158 the proxy, the notebook web application might fail to connect to the server's
159 websockets, and present you with a warning at startup. In this case, you need
160 to configure your system not to use the proxy for the server's address.
179 161
180 162 For example, in Firefox, go to the Preferences panel, Advanced section,
181 163 Network tab, click 'Settings...', and add the address of the notebook server
@@ -8,12 +8,27 b" You don't need to know anything beyond Python to start using IPython \xe2\x80\x93 just ty"
8 8 commands as you would at the standard Python prompt. But IPython can do much
9 9 more than the standard prompt. Some key features are described here. For more
10 10 information, check the :ref:`tips page <tips>`, or look at examples in the
11 `IPython cookbook <http://wiki.ipython.org/index.php?title=Cookbook>`_.
11 `IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
12 12
13 13 If you've never used Python before, you might want to look at `the official
14 14 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
15 15 Python <http://diveintopython.org/toc/index.html>`_.
16 16
17 The four most helpful commands
18 ===============================
19
20 The four most helpful commands, as well as their brief description, is shown
21 to you in a banner, every time you start IPython:
22
23 ========== =========================================================
24 command description
25 ========== =========================================================
26 ? Introduction and overview of IPython's features.
27 %quickref Quick reference.
28 help Python's own help system.
29 object? Details about 'object', use 'object??' for extra details.
30 ========== =========================================================
31
17 32 Tab completion
18 33 ==============
19 34
@@ -31,16 +46,19 b' including docstrings, function definition lines (for call arguments) and'
31 46 constructor details for classes. To get specific information on an object, you
32 47 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
33 48
49 .. _magics_explained:
50
34 51 Magic functions
35 52 ===============
36 53
37 54 IPython has a set of predefined 'magic functions' that you can call with a
38 55 command line style syntax. There are two kinds of magics, line-oriented and
39 cell-oriented. Line magics are prefixed with the ``%`` character and work much
56 cell-oriented. **Line magics** are prefixed with the ``%`` character and work much
40 57 like OS command-line calls: they get as an argument the rest of the line, where
41 arguments are passed without parentheses or quotes. Cell magics are prefixed
42 with a double ``%%``, and they are functions that get as an argument not only
43 the rest of the line, but also the lines below it in a separate argument.
58 arguments are passed without parentheses or quotes. **Cell magics** are
59 prefixed with a double ``%%``, and they are functions that get as an argument
60 not only the rest of the line, but also the lines below it in a separate
61 argument.
44 62
45 63 The following examples show how to call the builtin ``timeit`` magic, both in
46 64 line and cell mode::
@@ -58,34 +76,41 b' The builtin magics include:'
58 76 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
59 77 ``%recall``, etc.
60 78 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
61 etc.
62 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
79 ``%automagic``, etc.
80 - Other functions such as ``%reset``, ``%timeit``, ``%%file``, ``%load``, or
81 ``%paste``.
63 82
64 You can always call them using the % prefix, and if you're calling a line magic
65 on a line by itself, you can omit even that (cell magics must always have the
66 ``%%`` prefix)::
83 You can always call them using the ``%`` prefix, and if you're calling a line
84 magic on a line by itself, you can omit even that::
67 85
68 86 run thescript.py
69 87
88 You can toggle this behavior by running the ``%automagic`` magic. Cell magics
89 must always have the ``%%`` prefix.
90
70 91 A more detailed explanation of the magic system can be obtained by calling
71 92 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
72 93 read its docstring. To see all the available magic functions, call
73 94 ``%lsmagic``.
74 95
96 .. seealso::
97
98 `Cell magics`_ example notebook
99
75 100 Running and Editing
76 101 -------------------
77 102
78 The %run magic command allows you to run any python script and load all of its
79 data directly into the interactive namespace. Since the file is re-read from
80 disk each time, changes you make to it are reflected immediately (unlike
81 imported modules, which have to be specifically reloaded). IPython also includes
82 :ref:`dreload <dreload>`, a recursive reload function.
103 The ``%run`` magic command allows you to run any python script and load all of
104 its data directly into the interactive namespace. Since the file is re-read
105 from disk each time, changes you make to it are reflected immediately (unlike
106 imported modules, which have to be specifically reloaded). IPython also
107 includes :ref:`dreload <dreload>`, a recursive reload function.
83 108
84 %run has special flags for timing the execution of your scripts (-t), or for
85 running them under the control of either Python's pdb debugger (-d) or
109 ``%run`` has special flags for timing the execution of your scripts (-t), or
110 for running them under the control of either Python's pdb debugger (-d) or
86 111 profiler (-p).
87 112
88 The %edit command gives a reasonable approximation of multiline editing,
113 The ``%edit`` command gives a reasonable approximation of multiline editing,
89 114 by invoking your favorite editor on the spot. IPython will execute the
90 115 code you type in there as if it were typed interactively.
91 116
@@ -153,11 +178,12 b' visited directories and allows you to go to any previously visited one.'
153 178 Configuration
154 179 =============
155 180
156 Much of IPython can be tweaked through configuration. To get started, use the
157 command ``ipython profile create`` to produce the default config files. These
158 will be placed in :file:`~/.ipython/profile_default` or
159 :file:`~/.config/ipython/profile_default`, and contain comments explaining what
160 the various options do.
181 Much of IPython can be tweaked through :ref:`configuration <config_overview>`.
182 To get started, use the command ``ipython profile create`` to produce the
183 default config files. These will be placed in
184 :file:`~/.ipython/profile_default` or
185 :file:`~/.config/ipython/profile_default`, and contain comments explaining
186 what the various options do.
161 187
162 188 Profiles allow you to use IPython for different tasks, keeping separate config
163 189 files and history for each one. More details in :ref:`the profiles section
@@ -173,7 +199,4 b' as the IPython shell is constructed, before any other code or scripts you have'
173 199 specified. The files will be run in order of their names, so you can control the
174 200 ordering with prefixes, like ``10-myimports.py``.
175 201
176 .. note::
177
178 Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
179 in :file:`ipython_config.py` for similar behavior in 0.11.
202 .. include:: ../links.txt
@@ -23,6 +23,7 b''
23 23 .. _ipython_github_repo: http://github.com/ipython/ipython/
24 24 .. _ipython_downloads: http://ipython.org/download.html
25 25 .. _ipython_pypi: http://pypi.python.org/pypi/ipython
26 .. _nbviewer: http://nbviewer.ipython.org
26 27
27 28 .. _ZeroMQ: http://zeromq.org
28 29
@@ -46,7 +47,7 b''
46 47 .. _numpy: http://numpy.scipy.org
47 48 .. _scipy: http://www.scipy.org
48 49 .. _scipy_conference: http://conference.scipy.org
49 .. _matplotlib: http://matplotlib.sourceforge.net
50 .. _matplotlib: http://matplotlib.org
50 51 .. _pythonxy: http://www.pythonxy.com
51 52 .. _ETS: http://code.enthought.com/projects/tool-suite.php
52 53 .. _EPD: http://www.enthought.com/products/epd.php
@@ -72,4 +73,29 b''
72 73 .. _indefero: http://www.indefero.net
73 74 .. _git: http://git-scm.com
74 75 .. _github: http://github.com
75 .. _MarkDown: http://daringfireball.net/projects/markdown/
76 .. _Markdown: http://daringfireball.net/projects/markdown/syntax
77
78 .. _Running Code in the IPython Notebook: notebook_p1_
79 .. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
80
81 .. _Basic Output: notebook_p2_
82 .. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
83
84 .. _Plotting with Matplotlib: notebook_p3_
85 .. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
86
87 .. _Markdown Cells: notebook_p4
88 .. _notebook_p4: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb
89
90 .. _Rich Display System: notebook_p5_
91 .. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
92
93 .. _notebook_custom_display: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Custom%20Display%20Logic.ipynb
94
95 .. _Frontend/Kernel Model: notebook_two_proc_
96 .. _notebook_two_proc: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Frontend-Kernel%20Model.ipynb
97
98 .. _Cell magics: notebook_cell_magics_
99 .. _notebook_cell_magics: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Cell%20Magics.ipynb
100
101
@@ -18,9 +18,9 b' interactive and exploratory computing. To support this goal, IPython'
18 18 has three main components:
19 19
20 20 * An enhanced interactive Python shell.
21 * A decoupled two-process communication model, which allows for multiple
22 clients to connect to a computation kernel, most notably the web-based
23 :ref:`notebook <htmlnotebook>`
21 * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
22 allows for multiple clients to connect to a computation kernel, most notably
23 the web-based :ref:`notebook <htmlnotebook>`
24 24 * An architecture for interactive parallel computing.
25 25
26 26 All of IPython is open source (released under the revised BSD license).
@@ -197,7 +197,7 b' Decoupled two-process model'
197 197
198 198 IPython has abstracted and extended the notion of a traditional
199 199 *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation*
200 into its own process. We call this process a kernel: it receives execution
200 into its own process. We call this process a **kernel**: it receives execution
201 201 instructions from clients and communicates the results back to them.
202 202
203 203 This decoupling allows us to have several clients connected to the same
@@ -222,6 +222,10 b' You can read more about using :ref:`ipython qtconsole <qtconsole>`, and'
222 222 <messaging>` which documents the protocol for communication between kernels
223 223 and clients.
224 224
225 .. seealso::
226
227 `Frontend/Kernel Model`_ example notebook
228
225 229
226 230 Interactive parallel computing
227 231 ==============================
@@ -283,3 +287,4 b' IPython is known to work on the following operating systems:'
283 287
284 288 See :ref:`here <install_index>` for instructions on how to install IPython.
285 289
290 .. include:: links.txt
General Comments 0
You need to be logged in to leave comments. Login now