diff --git a/docs/source/interactive/nbconvert.rst b/docs/source/interactive/nbconvert.rst index b3672d0..6736277 100644 --- a/docs/source/interactive/nbconvert.rst +++ b/docs/source/interactive/nbconvert.rst @@ -67,7 +67,7 @@ The currently supported export formats are: * ``--to markdown`` Simple markdown output. Markdown cells are unaffected, - and code cells are placed in triple-backtick (``\`\`\```) blocks. + and code cells are placed in triple-backtick (```````) blocks. * ``--to rst`` diff --git a/docs/source/interactive/notebook.rst b/docs/source/interactive/notebook.rst index ae5dbef..9303b37 100644 --- a/docs/source/interactive/notebook.rst +++ b/docs/source/interactive/notebook.rst @@ -102,14 +102,16 @@ via the new nbconvert_ command. Furthermore, any ``.ipynb`` notebook document available from a public URL can be shared via the `IPython Notebook Viewer `_ service. -This service loads the notebook document from the URL and will -render it as a static web page. The results may thus be shared with a +This service loads the notebook document from the URL and renders +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. NbViewer is simply NbConvert as a simple heroku webservice. +IPython themselves. NbViewer is simply nbconvert_ as a simple webservice. See the :ref:`installation documentation ` for directions on how to install the notebook and its dependencies. +.. _nbconvert: ./nbconvert.html + .. _nbviewer: http://nbviewer.ipython.org .. note:: @@ -144,11 +146,11 @@ source code files into the notebook list area. You can open an existing notebook directly, without having to go via the -dashboard, with: +dashboard, with:: ipython notebook my_notebook -The `.ipynb` extension is assumed if no extension is given. +The ``.ipynb`` extension is assumed if no extension is given. The `File | Open...` menu option will open the dashboard in a new browser tab, to allow you to select a current notebook @@ -313,19 +315,6 @@ correctly. This is much more convenient for interactive exploration than breaking up a computation into scripts that must be executed together, as was previously necessary, especially if parts of them take a long time to run -The only significant limitation that the Notebook currently has, compared to -the Qt console, is that it cannot run any code that expects input from the -kernel (such as scripts that call :func:`raw_input`). Very importantly, this -means that the ``%debug`` magic does *not* currently work in the notebook! - -This limitation will be overcome in the future, but in the meantime, there is -a simple solution for debugging: you can attach a Qt console to your existing -notebook kernel, and run ``%debug`` from the Qt console. -If your notebook is running on a local computer (i.e. if you are accessing it -via your localhost address at ``127.0.0.1``), then you can just type -``%qtconsole`` in the notebook and a Qt console will open up, connected to -that same kernel. - At certain moments, it may be necessary to interrupt a calculation which is taking too long to complete. This may be done with the ``Kernel | Interrupt`` menu option, or the :kbd:``Ctrl-i`` keyboard shortcut. @@ -334,7 +323,12 @@ process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.`` shortcut. This gives an equivalent state to loading the notebook document afresh. - +A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the +menu option ``File | Download as``. Choosing the ``.py`` option downloads a +Python ``.py`` script, in which all output has been removed and the content of +Markdown cells in comment areas. See ref:`below ` for more +details on the notebook format. + .. warning:: While in simple cases you can "roundtrip" a notebook to Python, edit the @@ -558,14 +552,13 @@ on available options, use:: $ ipython profile create -.. seealso: +.. seealso:: :ref:`config_overview`, in particular :ref:`Profiles`. -Importing `.py` files ----------------------- - +Importing ``.py`` files +----------------------- ``.py`` files will be imported into the IPython Notebook as a notebook with the same basename, but an ``.ipynb`` extension, located in the notebook @@ -574,8 +567,24 @@ all the code in the ``.py`` file. You can later manually partition this into individual cells using the ``Edit | Split Cell`` menu option, or the :kbd:`Ctrl-m -` keyboard shortcut. -.. Alternatively, prior to importing the ``.py``, you can manually add ``# < -nbformat>2`` at the start of the file, and then add separators for -text and code cells, to get a cleaner import with the file already broken into -individual cells. +Note that ``.py`` scripts obtained from a notebook document using nbconvert_ +maintain the structure of the notebook in comments. Reimporting such a +script back into the Notebook will preserve this structxure. + +.. warning:: + + You can "roundtrip" a notebook to Python, by exporting the + notebook to a ``.py`` script, editing the script, and then importing it back + into the Notebook without loss of main content. However, + in general this is *not guaranteed* to work. First, there is extra metadata + saved in the notebook that may not be saved to the ``.py`` format. Second, + as the notebook format evolves in complexity, there will be attributes of + the notebook that will not survive a roundtrip through the Python form. You + should think of the Python format as a way to output a script version of a + notebook and the import capabilities as a way to load existing code to get + a notebook started. But the Python version is *not* an alternate notebook + format. + +.. seealso:: + :ref:`notebook_format` diff --git a/docs/source/interactive/working_remotely.rst b/docs/source/interactive/working_remotely.rst index ab4eb9d..5dcbcd2 100644 --- a/docs/source/interactive/working_remotely.rst +++ b/docs/source/interactive/working_remotely.rst @@ -5,10 +5,15 @@ Working remotely The IPython Notebook web app is based on a server-client structure. -This server uses a two-process kernel architecture based on ZeroMQ, as well as -Tornado for serving HTTP requests. Other clients may connect to the same +This server uses a two-process kernel architecture based on ZeroMQ_, as well +as Tornado_ for serving HTTP requests. Other clients may connect to the same underlying IPython kernel; see below. +.. _ZeroMQ: http://zeromq.org + +.. _Tornado: http://www.tornadoweb.org + + .. _notebook_security: Security @@ -58,7 +63,7 @@ the command:: Your browser will warn you of a dangerous certificate because it is self-signed. If you want to have a fully compliant certificate that will not raise warnings, it is possible (but rather involved) to obtain one, -`as explained in detailed in this tutorial`__. +as explained in detail in `this tutorial`__. .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a- secure-sertificate-for-free.ars