upstream/ipython Commit - r12098:20cd990c

major doc update for 1.0 release...

Paul Ivanov -

r12098:20cd990c

parent child

docs/source/_templates/htmlnotebook.html

0 created 644 +9 0

@@ -0,0 +1,9
	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>

docs/source/conf.py

0 +3 -1

             # -*- coding: utf-8 -*-
             #
             # IPython documentation build configuration file.
             # NOTE: This file has been edited manually from the auto-generated one from
             # sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
             # needed, generate a scratch one and merge by hand any new fields needed.
             #
             # This file is execfile()d with the current directory set to its containing dir.
             #
             # The contents of this file are pickled, so don't put values in the namespace
             # that aren't pickleable (module imports are okay, they're removed automatically).
             #
             # All configuration values have a default value; values that are commented out
             # serve to show the default value.
             import sys, os
             ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
             if ON_RTD:
                 # Mock the presence of matplotlib, which we don't have on RTD
                 # see
                 # http://read-the-docs.readthedocs.org/en/latest/faq.html
                 tags.add('rtd')
             # If your extensions are in another directory, add it here. If the directory
             # is relative to the documentation root, use os.path.abspath to make it
             # absolute, like shown here.
             sys.path.insert(0, os.path.abspath('../sphinxext'))
             # We load the ipython release info into a dict by explicit execution
             iprelease = {}
             execfile('../../IPython/core/release.py',iprelease)
             # General configuration
             # ---------------------
             # Add any Sphinx extension module names here, as strings. They can be extensions
             # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
             extensions = [
                 'matplotlib.sphinxext.mathmpl',
                 'matplotlib.sphinxext.only_directives',
                 'matplotlib.sphinxext.plot_directive',
                 'sphinx.ext.autodoc',
                 'sphinx.ext.doctest',
                 'sphinx.ext.inheritance_diagram',
                 'IPython.sphinxext.ipython_console_highlighting',
                 'IPython.sphinxext.ipython_directive',
                 'numpydoc',  # to preprocess docstrings
                 'github',  # for easy GitHub links
             ]
             if ON_RTD:
                 # Remove extensions not currently supported on RTD
                 extensions.remove('matplotlib.sphinxext.only_directives')
                 extensions.remove('matplotlib.sphinxext.mathmpl')
                 extensions.remove('matplotlib.sphinxext.plot_directive')
                 extensions.remove('IPython.sphinxext.ipython_directive')
                 extensions.remove('IPython.sphinxext.ipython_console_highlighting')
             # Add any paths that contain templates here, relative to this directory.
             templates_path = ['_templates']
             # The suffix of source filenames.
             source_suffix = '.rst'
             if iprelease['_version_extra']:
                 rst_prolog = """
                 .. note::
                     This documentation is for a development version of IPython. There may be
                     significant differences from the latest stable release (0.13.2).
                 """
             # The master toctree document.
             master_doc = 'index'
             # General substitutions.
             project = 'IPython'
             copyright = '2008, The IPython Development Team'
             # ghissue config
             github_project_url = "https://github.com/ipython/ipython"
             # The default replacements for |version| and |release|, also used in various
             # other places throughout the built documents.
             #
             # The full version, including alpha/beta/rc tags.
             codename = iprelease['codename']
             release = "%s: %s" % (iprelease['version'], codename)
             # Just the X.Y.Z part, no '-dev'
             version = iprelease['version'].split('-', 1)[0]
             # There are two options for replacing |today|: either, you set today to some
             # non-false value, then it is used:
             #today = ''
             # Else, today_fmt is used as the format for a strftime call.
             today_fmt = '%B %d, %Y'
             # List of documents that shouldn't be included in the build.
             #unused_docs = []
             # List of directories, relative to source directories, that shouldn't be searched
             # for source files.
             exclude_dirs = ['attic']
             # If true, '()' will be appended to :func: etc. cross-reference text.
             #add_function_parentheses = True
             # If true, the current module name will be prepended to all description
             # unit titles (such as .. function::).
             #add_module_names = True
             # If true, sectionauthor and moduleauthor directives will be shown in the
             # output. They are ignored by default.
             #show_authors = False
             # The name of the Pygments (syntax highlighting) style to use.
             pygments_style = 'sphinx'
             # Options for HTML output
             # -----------------------
             # The style sheet to use for HTML and HTML Help pages. A file of that name
             # must exist either in Sphinx' static/ path, or in one of the custom paths
             # given in html_static_path.
             html_style = 'default.css'
             # The name for this set of Sphinx documents.  If None, it defaults to
             # "<project> v<release> documentation".
             #html_title = None
             # The name of an image file (within the static path) to place at the top of
             # the sidebar.
             #html_logo = None
             # Add any paths that contain custom static files (such as style sheets) here,
             # relative to this directory. They are copied after the builtin static files,
             # so a file named "default.css" will overwrite the builtin "default.css".
             html_static_path = ['_static']
             # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
             # using the given strftime format.
             html_last_updated_fmt = '%b %d, %Y'
             # If true, SmartyPants will be used to convert quotes and dashes to
             # typographically correct entities.
             #html_use_smartypants = True
             # Custom sidebar templates, maps document names to template names.
             #html_sidebars = {}
             # Additional templates that should be rendered to pages, maps page names to
             # template names.
-            #html_additional_pages = {}
+            html_additional_pages = {
+                                     'interactive/htmlnotebook': 'htmlnotebook.html',
+            }
             # If false, no module index is generated.
             #html_use_modindex = True
             # If true, the reST sources are included in the HTML build as _sources/<name>.
             #html_copy_source = True
             # If true, an OpenSearch description file will be output, and all pages will
             # contain a <link> tag referring to it.  The value of this option must be the
             # base URL from which the finished HTML is served.
             #html_use_opensearch = ''
             # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
             #html_file_suffix = ''
             # Output file base name for HTML help builder.
             htmlhelp_basename = 'ipythondoc'
             # Options for LaTeX output
             # ------------------------
             # The paper size ('letter' or 'a4').
             latex_paper_size = 'letter'
             # The font size ('10pt', '11pt' or '12pt').
             latex_font_size = '11pt'
             # Grouping the document tree into LaTeX files. List of tuples
             # (source start file, target name, title, author, document class [howto/manual]).
             latex_documents = [
                 ('index', 'ipython.tex', 'IPython Documentation',
                  ur"""The IPython Development Team""", 'manual', True),
                 ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
                  'Using IPython on Windows HPC Server 2008',
                  ur"Brian E. Granger", 'manual', True)
             ]
             # The name of an image file (relative to this directory) to place at the top of
             # the title page.
             #latex_logo = None
             # For "manual" documents, if this is true, then toplevel headings are parts,
             # not chapters.
             #latex_use_parts = False
             # Additional stuff for the LaTeX preamble.
             #latex_preamble = ''
             # Documents to append as an appendix to all manuals.
             #latex_appendices = []
             # If false, no module index is generated.
             latex_use_modindex = True
             # Options for texinfo output
             # --------------------------
             texinfo_documents = [
               (master_doc, 'ipython', 'IPython Documentation',
                'The IPython Development Team',
                'IPython',
                'IPython Documentation',
                'Programming',
 ),
             ]
             # Cleanup
             # -------
             # delete release info to avoid pickling errors from sphinx
             del iprelease

docs/source/install/install.rst

0 +1 -1

             Overview
             ========
             This document describes the steps required to install IPython.  IPython is
             organized into a number of subpackages, each of which has its own dependencies.
             All of the subpackages come with IPython, so you don't need to download and
             install them separately.  However, to use a given subpackage, you will need to
             install all of its dependencies.
             Please let us know if you have problems installing IPython or any of its
             dependencies. Officially, IPython requires Python 2.6, 2.7, 3.1, or 3.2.
             .. warning::
                 Since version 0.11, IPython has a hard syntax dependency on 2.6, and will no
                 longer work on Python <= 2.5. You can find older versions of IPython which
                 supported Python <= 2.5 `here <http://archive.ipython.org/release/>`_
             Some of the installation approaches use the :mod:`distribute` package and its
             :command:`easy_install` command line program.  In many scenarios, this provides
             the most simple method of installing IPython and its dependencies.  More
             information about :mod:`distribute` can be found on `its PyPI page
             <http://pypi.python.org/pypi/distribute>`__.
             .. note::
                On Windows, IPython has a hard dependency on :mod:`distribute`.  We hope to
                change this in the future, but for now on Windows, you *must* install
                :mod:`distribute`.
             More general information about installing Python packages can be found in
             `Python's documentation <http://docs.python.org>`_.
             Quickstart
             ==========
             If you have :mod:`distribute` installed and you are on OS X or Linux (not
             Windows), the following will download and install IPython *and* the main
             optional dependencies:
             .. code-block:: bash
                 $ easy_install ipython[all]
             This will get:
             - jinja2, needed for the notebook
             - sphinx, needed for nbconvert
             - pyzmq, needed for IPython's parallel computing features, qt console and
               notebook.
             - pygments, used by nbconvert and the Qt console for syntax highlighting.
             - tornado, needed by the web-based notebook
             - nose, used by the test suite.
             To run IPython's test suite, use the :command:`iptest` command:
             .. code-block:: bash
                 $ iptest
             Installing IPython itself
             =========================
             Given a properly built Python, the basic interactive IPython shell will work
             with no external dependencies.  However, some Python distributions
             (particularly on Windows and OS X), don't come with a working :mod:`readline`
             module.  The IPython shell will work without :mod:`readline`, but will lack
             many features that users depend on, such as tab completion and command line
             editing.  If you install IPython with :mod:`distribute`, (e.g. with
             `easy_install`), then the appropriate :mod:`readline` for your platform will be
             installed.  See below for details of how to make sure you have a working
             :mod:`readline`.
             Installation using easy_install
             -------------------------------
             If you have :mod:`distribute` installed, the easiest way of getting IPython is
             to simply use :command:`easy_install`:
             .. code-block:: bash
                 $ easy_install ipython
             That's it.
             Installation from source
             ------------------------
             If you don't want to use :command:`easy_install`, or don't have it installed,
             just grab the latest stable build of IPython from `here
             <http://ipython.org/download.html>`_.  Then do the following:
             .. code-block:: bash
                 $ tar -xzf ipython.tar.gz
                 $ cd ipython
                 $ python setup.py install
             If you are installing to a location (like ``/usr/local``) that requires higher
             permissions, you may need to run the last command with :command:`sudo`.
             Windows
             -------
             As mentioned above, on Windows, IPython requires :mod:`distribute`, and it also
             requires the PyReadline library to properly support coloring and keyboard
             management (features that the default windows console doesn't have).  So on
             Windows, the installation procedure is:
 . Install `distribute <http://pypi.python.org/pypi/distribute>`_.
 . Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_.  You can use
                the command ``easy_install pyreadline`` from a terminal, or the binary
                installer appropriate for your platform from the PyPI page.
 . Install IPython itself, which you can download from `PyPI
                <http://pypi.python.org/pypi/ipython>`_ or from `our site
                <http://ipython.org/download.html>`_.  Note that on Windows 7, you *must*
                right-click and 'Run as administrator' for the Start menu shortcuts to be
                created.
             IPython by default runs in a terminal window, but the normal terminal
             application supplied by Microsoft Windows is very primitive.  You may want to
             download the excellent and free Console_ application instead, which is a far
             superior tool.  You can even configure Console to give you by default an
             IPython tab, which is very convenient to create new IPython sessions directly
             from the working terminal.
             .. _Console:  http://sourceforge.net/projects/console
             Installing the development version
             ----------------------------------
             It is also possible to install the development version of IPython from our
             `Git <http://git-scm.com/>`_ source code repository.  To do this you will
             need to have Git installed on your system.  Then just do:
             .. code-block:: bash
                 $ git clone https://github.com/ipython/ipython.git
                 $ cd ipython
                 $ python setup.py install
             Some users want to be able to follow the development branch as it changes.  If
             you have :mod:`distribute` installed, this is easy. Simply replace the last
             step by:
             .. code-block:: bash
                 $ python setupegg.py develop
             This creates links in the right places and installs the command line script to
             the appropriate places.  Then, if you want to update your IPython at any time,
             just do:
             .. code-block:: bash
                 $ git pull
             Basic optional dependencies
             ===========================
             There are a number of basic optional dependencies that most users will want to
             get.  These are:
             * readline (for command line editing, tab completion, etc.)
             * nose (to run the IPython test suite)
             * pexpect (to use things like irunner)
             If you are comfortable installing these things yourself, have at it, otherwise
             read on for more details.
             readline
             --------
             As indicated above, on Windows, PyReadline is a *mandatory* dependency.
             PyReadline is a separate, Windows only implementation of readline that uses
             native Windows calls through :mod:`ctypes`. The easiest way of installing
             PyReadline is you use the binary installer available `here
             <http://pypi.python.org/pypi/pyreadline>`_.
             On OSX, if you are using the built-in Python shipped by Apple, you will be
             missing a full readline implementation as Apple ships instead a library called
             ``libedit`` that provides only some of readline's functionality.  While you may
             find libedit sufficient, we have occasional reports of bugs with it and several
             developers who use OS X as their main environment consider libedit unacceptable
             for productive, regular use with IPython.
             Therefore, we *strongly* recommend that on OS X you get the full
             :mod:`readline` module.  We will *not* consider completion/history problems to
             be bugs for IPython if you are using libedit.
             To get a working :mod:`readline` module, just do (with :mod:`distribute`
             installed):
             .. code-block:: bash
                 $ easy_install readline
             .. note::
                 Other Python distributions on OS X (such as fink, MacPorts and the official
                 python.org binaries) already have readline installed so you likely don't
                 have to do this step.
             When IPython is installed with :mod:`distribute`, (e.g. using the
             ``easy_install`` command), readline is added as a dependency on OS X, and
             PyReadline on Windows, and will be installed on your system.  However, if you
             do not use distribute, you may have to install one of these packages yourself.
             nose
             ----
             To run the IPython test suite you will need the :mod:`nose` package.  Nose
             provides a great way of sniffing out and running all of the IPython tests.  The
             simplest way of getting nose, is to use :command:`easy_install`:
             .. code-block:: bash
                 $ easy_install nose
             Another way of getting this is to do:
             .. code-block:: bash
                 $ easy_install ipython[test]
             For more installation options, see the `nose website
             <http://somethingaboutorange.com/mrl/projects/nose/>`_.
             Once you have nose installed, you can run IPython's test suite using the
             iptest command:
             .. code-block:: bash
                 $ iptest
             pexpect
             -------
             The pexpect_ package is used in IPython's :command:`irunner` script, as well as
             for managing subprocesses. IPython now includes a version of pexpect in
             :mod:`IPython.external`, but if you have installed pexpect, IPython will use
             that instead. On Unix platforms (including OS X), just do:
             .. code-block:: bash
                 $ easy_install pexpect
             Windows users are out of luck as pexpect does not run there.
             Dependencies for IPython.parallel (parallel computing)
             ======================================================
             :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`,
             which uses ZeroMQ for all communication.
             IPython.parallel provides a nice architecture for parallel computing, with a
             focus on fluid interactive workflows.  These features require just one package:
             PyZMQ.  See the next section for PyZMQ details.
             On a Unix style platform (including OS X), if you want to use
             :mod:`distribute`, you can just do:
             .. code-block:: bash
                 $ easy_install ipython[zmq]    # will include pyzmq
             Security in IPython.parallel is provided by SSH tunnels.  By default, Linux
             and OSX clients will use the shell ssh command, but on Windows, we also
             support tunneling with paramiko_.
             Dependencies for IPython.kernel.zmq
             ===================================
             pyzmq
             -----
             IPython 0.11 introduced some new functionality, including a two-process
             execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
             are found in the PyZMQ_ project, which is easy_install-able once you have
             ZeroMQ installed.  If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows,
             pyzmq has eggs that include ZeroMQ itself.
             IPython.kernel.zmq depends on pyzmq >= 2.1.4.
             Dependencies for the IPython QT console
             =======================================
             pyzmq
             -----
             Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
             PyZMQ.
             Qt
             --
             Also with 0.11, a new GUI was added using the work in :mod:`IPython.kernel.zmq`, which
             can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
             with either PyQt, which can be installed from the `PyQt website
             <http://www.riverbankcomputing.co.uk/>`_, or `PySide
             <http://www.pyside.org/>`_, from Nokia.
             pygments
             --------
             The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
             project, which is easy_install-able.
             .. _installnotebook:
             Dependencies for the IPython HTML notebook
             ==========================================
             The IPython notebook is a notebook-style web interface to IPython and can be
-            started withe command ``ipython notebook``.
+            started with the command ``ipython notebook``.
             pyzmq
             -----
             Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
             packages, the HTML notebook requires ZeroMQ and PyZMQ.
             Tornado
             -------
             The IPython notebook uses the Tornado_ project for its HTTP server.  Tornado 2.1
             is required, in order to support current versions of browsers, due to an update
             to the websocket protocol.
             Jinja
             -----
             The IPython notebook uses the Jinja_ templating tool to render HTML pages.
             MathJax
             -------
             The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
             in web browsers. Because MathJax is large, we don't include it with
             IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
             network connection, or want to use LaTeX without an internet connection at all,
             you can install MathJax locally.
             A quick and easy method is to install it from a python session::
                 from IPython.external.mathjax import install_mathjax
                 install_mathjax()
             If you need tighter configuration control, you can download your own copy
             of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
             When you have the file stored locally, install it with::
             	python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
             For unusual needs, IPython can tell you what directory it wants to find MathJax in::
             	python -m IPython.external.mathjax -d /some/other/mathjax
             By default Mathjax will be installed in your ipython profile directory, but you
             can make system wide install, please refer to the documentation and helper function
             of :mod:`IPython.external.mathjax`
             Browser Compatibility
             ---------------------
             The IPython notebook is officially supported on the following browers:
             * Chrome ≥ 13
             * Safari ≥ 5
             * Firefox ≥ 6
             The is mainly due to the notebook's usage of WebSockets and the flexible box model.
             The following browsers are unsupported:
             * Safari < 5
             * Firefox < 6
             * Chrome < 13
             * Opera (any): CSS issues, but execution might work
             * Internet Explorer < 10
             The following specific combinations are known **NOT** to work:
             * Safari, IPython 0.12, tornado ≥ 2.2.0
             * Safari with HTTPS connection to notebook and an untrusted certificate (websockets will fail)
             * The [diigo Chrome extension](http://help.diigo.com/tools/chrome-extension) seems to interfere with scrolling
             There are some early reports that the Notebook works on Internet Explorer 10, but we
             expect there will be some CSS issues related to the flexible box model.
             Dependencies for nbconvert (converting notebooks to various formats)
             ====================================================================
             pandoc
             ------
             The most important dependency of nbconvert is Pandoc_, a document format translation program.
             This is not a Python package, so it cannot be expressed as a regular IPython dependency with setuptools.
             To install pandoc on Linux, you can generally use your package manager::
                 sudo apt-get install pandoc
             On other platforms, you can get pandoc from `their website <http://johnmacfarlane.net/pandoc/installing.html>`_.
             .. _ZeroMQ: http://www.zeromq.org
             .. _PyZMQ: https://github.com/zeromq/pyzmq
             .. _paramiko: https://github.com/robey/paramiko
             .. _pygments: http://pygments.org
             .. _pexpect: http://www.noah.org/wiki/Pexpect
             .. _Jinja: http://jinja.pocoo.org
             .. _Sphinx: http://sphinx-doc.org
             .. _pandoc: http://johnmacfarlane.net/pandoc
             .. _Tornado: http://www.tornadoweb.org
             .. _MathJax: http://www.mathjax.org

docs/source/interactive/index.rst

0 +1 -1

             ==================================
             Using IPython for interactive work
             ==================================
             .. toctree::
                :maxdepth: 2
                tutorial
                tips
                reference
                shell
                qtconsole
                notebook
                nbconvert
-               working_remotely
+               public_server

docs/source/interactive/notebook.rst

0 +224 -322

             .. _htmlnotebook:
             The IPython Notebook
             ====================
-            The IPython Notebook is part of the IPython package, which aims to provide a
+            Introduction
-            powerful, interactive approach to scientific computation.
+            ------------
-            The IPython Notebook extends the previous text-console-based approach, and the
-            later Qt console, in a qualitatively new diretion, providing a web-based
+            The notebook extends the console-based approach to interactive computing in
-            application suitable for capturing the whole scientific computation process.
+            a qualitatively new direction, providing a web-based application suitable for
+            capturing the whole computation process: developing, documenting, and
+            executing code, as well as communicating the results.  The IPython notebook
+            combines two components:
+            **A web application**: a browser-based tool for interactive authoring of
+            documents which combine explanatory text, mathematics, computations and their
+            rich media output.
+            **Notebook documents**: a representation of all content visible in the web
+            application, including inputs and outputs of the computations, explanatory
+            text, mathematics, images, and rich media representations of objects.
             .. seealso::
-                :ref:`Installation requirements <installnotebook>` for the Notebook.
+                See the :ref:`installation documentation <installnotebook>` for directions
+                on how to install the notebook and its dependencies.
-            .. Basic structure
+            Main features of the web application
-            .. ---------------
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            Introduction
+            * In-browser editing for code, with automatic syntax highlighting,
-            ------------
+              indentation, and tab completion/introspection.
-            The IPython Notebook combines two components:
+            * The ability to execute code from the browser, with the results of
+              computations attached to the code which generated them.
-            * **The IPython Notebook web application**:
+            * Displaying the result of computation using rich media representations, such
+              as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
+              rendered by the matplotlib_ library, can be included inline.
-                  The *IPython Notebook web app* is a browser-based tool for interactive
+            * In-browser editing for rich text using the Markdown_ markup language, which
-                  authoring of literate computations, in which explanatory text,
+              can provide commentary for the code, is not limited to plain text.
-                  mathematics, computations and rich media output may be combined. Input
-                  and output are stored in persistent cells that may be edited in-place.
-            * **Notebook documents**:
+            * The ability to easily include mathematical notation within markdown cells
+              using LaTeX, and rendered natively by MathJax_.
-                  *Notebook documents*, or *notebooks*, are plain text documents which
-                  record all inputs and outputs of the computations, interspersed with
-                  text, mathematics and HTML 5 representations of objects, in a literate
-                  style.
-            Since the similarity in names can lead to some confusion, in this
-            documentation we will  use capitalization of the word "notebook" to
-            distinguish the Notebook app and notebook documents, thinking of the
-            Notebook app as being a proper noun. We will also always refer to the
-            "Notebook app" when we are referring to the browser-based interface,
-            and usually to "notebook documents", instead of "notebooks", for added
-            precision.
-            We refer to the current state of the computational process taking place in the
+            .. _MathJax: http://www.mathjax.org/
-            Notebook app, i.e. the (numbered) sequence of input and output cells, as the
-            *notebook space*. Notebook documents provide an *exact*, *one-to-one* record
-            of all the content in the notebook space, as a plain text file in JSON format.
-            The Notebook app automatically saves, at certain intervals, the contents of
-            the notebook space to a notebook document stored on disk, with the same name
-            as the title of the notebook space, and the file extension ``.ipynb``. For
-            this reason, there is no confusion about using the same word "notebook" for
-            both the notebook space and the corresponding notebook document, since they are
-            really one and the same concept (we could say that they are "isomorphic").
-            Main features of the IPython Notebook web app
+            Notebook documents
-            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            ~~~~~~~~~~~~~~~~~~
+            Notebook documents contains the inputs and outputs of a interactive session as
+            well as additional text that accompanies the code but is not meant for
+            execution.  In this way, notebook files can serve as a complete computational
+            record of a session, interleaving executable code with explanatory text,
+            mathematics, and rich representations of resulting objects. These documents
+            are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
+            JSON is a plain text format, they can be version-controlled and shared with
+            colleagues.
-            The main features of the IPython Notebook app include:
+            .. _JSON: http://en.wikipedia.org/wiki/JSON
-            * In-browser editing for code, with automatic syntax highlighting and
+            Notebooks may be exported to a range of static formats, including HTML (for
-              indentation and tab completion/introspection.
+            example, for blog posts), reStructeredText, LaTeX, PDF, and slide shows, via
+            the new :ref:`nbconvert <nbconvert>` command.
-            * Literate combination of code with rich text using the Markdown_ markup
+            Furthermore, any  ``.ipynb`` notebook document available from a public
-              language.
+            URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
+            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.
+            In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
+            so you can do your own static conversions with nbconvert, without relying on
+            nbviewer.
-            * Mathematics is easily included within the Markdown using LaTeX notation, and
-              rendered natively by MathJax_.
-            * Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result
-              of computations.
-            * Publication-quality figures in a range of formats (SVG / PNG), rendered by
+            .. seealso::
-              the matplotlib_ library, may be included inline and exported.
+                :ref:`Details on the notebook JSON file format <notebook_format>`
-            .. _MathJax: http://www.mathjax.org/
-            .. _matplotlib: http://matplotlib.org/
-            .. _Markdown: http://daringfireball.net/projects/markdown/syntax
+            Starting the notebook server
+            ----------------------------
-            Notebook documents
+            You can start running a notebook server from the command line using the
-            ~~~~~~~~~~~~~~~~~~
+            following command::
-            Notebook document files are simple JSON_ files with the
+                ipython notebook
-            extension ``.ipynb``.
-            Since JSON is just plain text, they can be easily version-controlled and shared with colleagues.
-            The notebook stores a *complete*, *reproducible*, *one-to-one* copy of the state of the
-            computational state as it is inside the Notebook app. All computations
-            carried out, and the corresponding results obtained, can be combined in
-            a literate way, interleaving executable code with rich text, mathematics,
-            and rich representations of objects.
-            .. _JSON: http://en.wikipedia.org/wiki/JSON
+            This will print some information about the notebook server in your console,
+            and open a web browser to the URL of the web application (by default,
+            ``http://127.0.0.1:8888``).
-            Notebooks may easily be exported to a range of static formats, including
+            The landing page of the IPython notebook web application, the **dashboard**,
-            HTML (for example, for blog posts), PDF and slide shows,
+            shows the notebooks currently available in the notebook directory (by default,
-            via the new nbconvert_ command.
+            the directory from which the notebook server was started).
-            Furthermore, any  ``.ipynb`` notebook document available from a public
+            You can create new notebooks from the dashboard with the ``New Notebook``
-            URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ service.
+            button, or open existing ones by clicking on their name.  You can also drag
-            This service loads the notebook document from the URL and renders
+            and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
-            it as a static web page. The results may thus be shared with a
+            into the notebook list area.
-            colleague, or as a public blog post, without other users needing to install
-            IPython themselves.  NbViewer is simply nbconvert_ as a simple webservice.
-            See the :ref:`installation documentation <install_index>` for directions on
+            When starting a notebook server from the command line, you can also open a
-            how to install the notebook and its dependencies.
+            particular notebook directly, bypassing the dashboard, with ``ipython notebook
+            my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
+            given.
-            .. _nbconvert: ./nbconvert.html
+            When you are inside an open notebook, the `File | Open...` menu option will
+            open the dashboard in a new browser tab, to allow you to open another notebook
+            from the notebook directory or to create a new notebook.
-            .. _nbviewer: http://nbviewer.ipython.org
             .. note::
                You can start more than one notebook server at the same time, if you want
                to work on notebooks in different directories.  By default the first
                notebook server starts on port 8888, and later notebook servers search for
                ports near that one.  You can also manually specify the port with the
                ``--port`` option.
+            Creating a new notebook document
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            Basic workflow in the IPython Notebook web app
+            A new notebook may be created at any time, either from the dashboard, or using
-            ----------------------------------------------
+            the `File | New` menu option from within an active notebook. The new notebook
+            is created within the same directory and will open in a new browser tab. It
-            Starting up
+            will also be reflected as a new entry in the notebook list on the dashboard.
-            ~~~~~~~~~~~~
-            You can start running the Notebook web app using the following command::
-                $ ipython notebook
-            (Here, and in the sequel, the initial ``$`` represents the shell prompt,
+            Opening notebooks
-            indicating that the command is to be run from the command line in a shell.)
+            ~~~~~~~~~~~~~~~~~
+            An open notebook has **exactly one** interactive session connected to an
+            :ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
+            and communicate back results.  This kernel remains active if the web browser
+            window is closed, and reopening the same notebook from the dashboard will
+            reconnect the web application to the same kernel. In the dashboard, notebooks
+            with an active kernel have a ``Shutdown`` button next to them, whereas
+            notebooks without an active kernel have a ``Delete`` button in its place.
-            The landing page of the IPython Notebook application, the *dashboard*, shows
+            Other clients may connect to the same underlying IPython kernel.
-            the notebooks currently available in the *notebook directory* (By default, the directory
+            The notebook server always prints to the terminal the full details of
-            from which the notebook was started).
+            how to connect to each kernel, with messages such as the following::
-            You can create new notebooks from the dashboard with the ``New Notebook``
-            button, or open existing ones by clicking on their name.
-            You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python
-            source code files into the notebook list area.
+                [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
-            You can open an existing notebook directly, without having to go via the
+            This long string is the kernel's ID which is sufficient for getting the
-            dashboard, with::
+            information necessary to connect to the kernel.  You can also request this
+            connection data by running the ``%connect_info`` :ref:`magic
+            <magics_explained>`. This will print the same ID information as well as the
+            content of the JSON data structure it contains.
-              ipython notebook my_notebook
+            You can then, for example, manually start a Qt console connected to the *same*
+            kernel from the command line, by passing a portion of the ID::
-            The ``.ipynb`` extension is assumed if no extension is given.
+                $ ipython qtconsole --existing 87f7d2c0
-            The `File | Open...` menu option will open the dashboard in a new browser tab,
+            Without an ID, ``--existing`` will  connect to the most recently
-            to allow you to select a current notebook
+            started kernel. This can also be done by running the ``%qtconsole``
-            from the notebook directory or to create a new notebook.
+            :ref:`magic <magics_explained>` in the notebook.
+            .. seealso::
+                :ref:`ipythonzmq`
             Notebook user interface
-            ~~~~~~~~~~~~~~~~~~~~~~~
+            -----------------------
-            When you open a new notebook document in the Notebook, you will be presented
-            with the title associated to the notebook space/document, a *menu bar*, a
-            *toolbar* and an empty *input cell*.
-            Notebook title
-            ^^^^^^^^^^^^^^
-            The title of the notebook document that is currently being edited is displayed
-            at the top of the page, next to the ``IP[y]: Notebook`` logo. This title may
-            be edited directly by clicking on it. The title is reflected in the name of
-            the ``.ipynb`` notebook document file that is saved.
-            Menu bar
+            When you create a new notebook document, you will be presented with the
-            ^^^^^^^^
+            **notebook name**, a **menu bar**, a **toolbar** and an empty **code
-            The menu bar presents different options that may be used to manipulate the way
+            cell**.
-            the Notebook functions.
-            Toolbar
+            **notebook name**: The name of the notebook document is displayed at the top
-            ^^^^^^^
+            of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
-            The tool bar gives a quick way of accessing the most-used operations within
+            of the ``.ipynb`` notebook document file.  Clicking on the notebook name
-            the Notebook, by clicking on an icon.
+            brings up a dialog which allows you to rename it. Thus, renaming a notebook
+            from "Untitled0" to "My first notebook" in the browser, renames the
+            ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
+            **menu bar**: The menu bar presents different options that may be used to
+            manipulate the way the notebook functions.
-            Creating a new notebook document
+            **toolbar**: The tool bar gives a quick way of performing the most-used
-            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            operations within the notebook, by clicking on an icon.
-            A new notebook space/document may be created at any time, either from the
+            **code cell**: the default type of cell, read on for an explanation of cells
-            dashboard, or using the `File | New` menu option from within an active
-            notebook. The new notebook is created within the same directory and
-            will open in a new browser tab. It will also be reflected as a new entry in
-            the notebook list on the dashboard.
             Structure of a notebook document
             --------------------------------
-            Input cells
+            The notebook consists of a sequence of cells.  A cell is a multi-line
-            ~~~~~~~~~~~
+            text input field, and its contents can be executed by using
-            Input cells are at the core of the functionality of the IPython Notebook.
+            :kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
-            They are regions in the document in which you can enter different types of
+            `Cell | Run` in the menu bar.  The execution behavior of a cell is determined
-            text and commands. To *execute* or *run* the *current cell*, i.e. the cell
+            the cell's type.  There are four types of cells: **code cells**, **markdown
-            under the cursor, you can use the :kbd:`Shift-Enter` key combination.
+            cells**, **raw cells** and **heading cells**.  Every cell starts off
-            This tells the Notebook app to perform the relevant operation for each type of
+            being a **code cell**, but its type can be changed by using a dropdown on the
-            cell (see below), and then to display the resulting output.
+            toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
+            <keyboard-shortcuts>`.
-            The notebook consists of a sequence of input cells, labelled ``In[n]``, which
-            may be executed in a non-linear way, and outputs ``Out[n]``, where ``n`` is a
-            number which denotes the order in which the cells were executed over the
-            history of the computational process. The contents of all of these cells are
-            accessible as Python variables with the same names, forming a complete record
-            of the history of the computation.
-            Input cell types
-            ~~~~~~~~~~~~~~~~
-            Each IPython input cell has a *cell type*, of which there is a restricted
-            number. The type of a cell may be set by using the cell type dropdown on the
-            toolbar, or via the following keyboard shortcuts:
-            * **code**: :kbd:`Ctrl-m y`
-            * **markdown**: :kbd:`Ctrl-m m`
-            * **raw**: :kbd:`Ctrl-m t`
-            * **heading**: :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
-            Upon initial creation, each input cell is by default a code cell.
             Code cells
-            ^^^^^^^^^^
+            ~~~~~~~~~~
-            A *code input cell* allows you to edit code inline within the cell, with full
+            A *code cell* allows you to edit and write new code, with full syntax
-            syntax highlighting and autocompletion/introspection. By default, the language
+            highlighting and tab completion. By default, the language associated to a code
-            associated to a code cell is Python, but other languages, such as ``julia``
+            cell is Python, but other languages, such as ``Julia`` and ``R``, can be
-            and ``R``, can be handled using magic commands (see below).
+            handled using :ref:`cell magic commands <magics_explained>`.
-            When a code cell is executed with :kbd:`Shift-Enter`, the code that it
+            When a code cell is executed, code that it contains is sent to the kernel
-            contains is transparently exported and run in that language (with automatic
+            associated with the notebook.  The results that are returned from this
-            compiling, etc., if necessary). The result that is returned from this
+            computation  are then displayed in the notebook as the cell's *output*. The
-            computation  is then displayed in the notebook space as the cell's
+            output is not limited to text, with many other possible forms of output are
-            *output*. If this output is of a textual nature, it is placed into a
+            also possible, including ``matplotlib`` figures and HTML tables (as used, for
-            numbered *output cell*. However, many other possible forms of output are also
+            example, in the ``pandas`` data analysis package). This is known as IPython's
-            possible, including ``matplotlib`` figures and HTML tables (as used, for
-            example, in the ``pandas`` data analyis package). This is known as IPython's
             *rich display* capability.
+            .. seealso::
+                `Basic Output`_  example notebook
+                `Rich Display System`_  example notebook
             Markdown cells
-            ^^^^^^^^^^^^^^
+            ~~~~~~~~~~~~~~
             You can document the computational process in a literate way, alternating
             descriptive text with code, using *rich text*. In IPython this is accomplished
             by marking up text with the Markdown language. The corresponding cells are
-            called *Markdown input cells*. The Markdown language provides a simple way to
+            called *Markdown cells*. The Markdown language provides a simple way to
             perform this text markup, that is, to specify which parts of the text should
             be emphasized (italics), bold, form lists, etc.
-            When a Markdown input cell is executed, the Markdown code is converted into
+            When a Markdown cell is executed, the Markdown code is converted into
-            the corresponding formatted rich text. This output then *replaces* the
+            the corresponding formatted rich text. Markdown allows arbitrary HTML code for
-            original Markdown input cell, leaving just the visually-significant marked up
+            formatting.
-            rich text.  Markdown allows arbitrary HTML code for formatting.
             Within Markdown cells, you can also include *mathematics* in a straightforward
             way, using standard LaTeX notation: ``$...$`` for inline mathematics and
             ``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
             the LaTeX portions are automatically rendered in the HTML output as equations
             with high quality typography. This is made possible by MathJax_, which
             supports a `large subset <mathjax_tex>`_ of LaTeX functionality
             .. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html
             Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
             `amsmath` package) also work, such as
             ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
             New LaTeX macros may be defined using standard methods,
             such as ``\newcommand``, by placing them anywhere *between math delimiters* in
             a Markdown cell. These definitions are then available throughout the rest of
-            the IPython session. (Note, however, that more care must be taken when using
+            the IPython session.
-            nbconvert_ to output to LaTeX).
+            .. seealso::
+                `Markdown Cells`_ example notebook
-            Raw input cells
+            Raw cells
-            ~~~~~~~~~~~~~~~
+            ~~~~~~~~~
-            *Raw* input cells provide a place in which you can write *output* directly.
+            *Raw* cells provide a place in which you can write *output* directly.
-            Raw cells are not evaluated by the Notebook, and have no output.
+            Raw cells are not evaluated by the notebook.
-            When passed through nbconvert, Raw cells arrive in the destination format unmodified,
+            When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
-            allowing you to type full latex into a raw cell, which will only be rendered
+            destination format unmodified. For example, this allows you to type full LaTeX
-            by latex after conversion by nbconvert.
+            into a raw cell, which will only be rendered by LaTeX after conversion by
+            nbconvert.
             Heading cells
             ~~~~~~~~~~~~~
             You can provide a conceptual structure for your computational document as a
             whole using different levels of headings; there are 6 levels available, from
             level 1 (top level) down to level 6 (paragraph). These can be used later for
-            constructing tables of contents, etc.
+            constructing tables of contents, etc.  As with Markdown cells, a heading
+            cell is replaced by a rich text rendering of the heading when the cell is
-            As with Markdown cells, a heading input cell is replaced by a rich text
+            executed.
-            rendering of the heading when the cell is executed.
             Basic workflow
             --------------
             The normal workflow in a notebook is, then, quite similar to a standard
             IPython session, with the difference that you can edit cells in-place multiple
             times until you obtain the desired results, rather than having to
-            rerun separate scripts with the ``%run`` magic command. (Magic commands do,
+            rerun separate scripts with the ``%run`` magic command.
-            however, also work in the notebook; see below).
             Typically, you will work on a computational problem in pieces, organizing
             related ideas into cells and moving forward once previous parts work
             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
+            previously necessary, especially if parts of them take a long time to run.
             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``
+            taking too long to complete. This may be done with the `Kernel | Interrupt`
-            menu option, or the :kbd:``Ctrl-i`` keyboard shortcut.
+            menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
             Similarly, it may be necessary or desirable to restart the whole computational
-            process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.``
+            process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
-            shortcut. This gives an equivalent state to loading the notebook document
+            shortcut.
-            afresh.
-            A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the
+            A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
-            menu option ``File | Download as``. Choosing the ``.py`` option downloads a
+            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
+            Python ``.py`` script, in which all rich output has been removed and the
-            Markdown cells  in comment areas.  See ref:`below <notebook_format>` for more
+            content of markdown cells have been inserted as comments.
-            details on the notebook format.
-            .. warning::
+            .. seealso::
-               While in simple cases you can "roundtrip" a notebook to Python, edit the
+                `Running Code in the IPython Notebook`_ example notebook
-               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
+                `Basic Output`_ example notebook
-               saved in the notebook that may not be saved to the ``.py`` format.  And as
-               the notebook format evolves in complexity, there will be attributes of the
+                :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
-               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.
+            .. _keyboard-shortcuts:
             Keyboard shortcuts
             ~~~~~~~~~~~~~~~~~~
             All actions in the notebook can be performed with the mouse, but keyboard
             shortcuts are also available for the most common ones. The essential shortcuts
             to remember are the following:
             * :kbd:`Shift-Enter`:  run cell
                 Execute the current cell, show output (if any), and jump to the next cell
-                below. If :kbd:`Shift-Enter` is invoked on the last input cell, a new code
+                below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
                 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
                 on its own *never* forces execution, but rather just inserts a new line in
-                the current input cell. :kbd:`Shift-Enter` is equivalent to clicking the
+                the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
                 ``Cell | Run`` menu item.
             * :kbd:`Ctrl-Enter`: run cell in-place
                 Execute the current cell as if it were in "terminal mode", where any
                 output is shown, but the cursor *remains* in the current cell. The cell's
                 entire contents are selected after execution, so you can just start typing
                 and only the new input will be in the cell. This is convenient for doing
                 quick experiments in place, or for querying things like filesystem
                 content, without needing to create additional cells that you may not want
                 to be saved in the notebook.
             * :kbd:`Alt-Enter`: run cell, insert below
-                Executes the current cell, shows the output, and inserts a *new* input
+                Executes the current cell, shows the output, and inserts a *new*
                 cell between the current cell and the cell below (if one exists). This
                 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
                 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
             * :kbd:`Ctrl-m`:
               This is the prefix for *all* other shortcuts, which consist of :kbd:`Ctrl-m`
               followed by a single letter or character. For example, if you type
               :kbd:`Ctrl-m h` (that is, the sole letter :kbd:`h` after :kbd:`Ctrl-m`),
               IPython will show you all the available keyboard shortcuts.
             ..
                 TODO: these live in IPython/html/static/notebook/js/quickhelp.js
                 They were last updated for IPython 1.0 release, so update them again for
                 future releases.
             Here is the complete set of keyboard shortcuts available:
             ============  ==========================
             **Shortcut**        **Action**
             ------------  --------------------------
             Shift-Enter    run cell
             Ctrl-Enter     run cell in-place
             Alt-Enter      run cell, insert below
             Ctrl-m x       cut cell
             Ctrl-m c       copy cell
             Ctrl-m v       paste cell
             Ctrl-m d       delete cell
             Ctrl-m z       undo last cell deletion
             Ctrl-m -       split cell
             Ctrl-m a       insert cell above
             Ctrl-m b       insert cell below
             Ctrl-m o       toggle output
             Ctrl-m O       toggle output scroll
             Ctrl-m l       toggle line numbers
             Ctrl-m s       save notebook
             Ctrl-m j       move cell down
             Ctrl-m k       move cell up
             Ctrl-m y       code cell
             Ctrl-m m       markdown cell
             Ctrl-m t       raw cell
             Ctrl-m 1-6     heading 1-6 cell
             Ctrl-m p       select previous
             Ctrl-m n       select next
             Ctrl-m i       interrupt kernel
             Ctrl-m .       restart kernel
             Ctrl-m h       show keyboard shortcuts
             ============  ==========================
-            Magic commands
-            --------------
-            Magic commands, or *magics*, are commands for controlling IPython itself.
-            They all begin with ``%`` and are entered into code input cells; the code
-            cells are executed as usual with :kbd:`Shift-Enter`.
-            The magic commands call special functions defined by IPython which manipulate
-            the computational state in certain ways.
-            There are two types of magics:
-              - **line magics**:
-                 These begin with a single ``%`` and take as arguments the rest of the
-                 *same line* of the code cell. Any other lines of the code cell are
-                 treated as if they were part of a standard code cell.
-              - **cell magics**:
-                  These begin with ``%%`` and operate on the *entire* remaining contents
-                  of the code cell.
-            Line magics
-            ~~~~~~~~~~~
-            Some of the available line magics are the following:
-              * ``%load filename``:
-                    Loads the contents of the file ``filename`` into a new code cell. This
-                    can be a URL for a remote file.
-              * ``%timeit code``:
-                  An easy way to time how long the single line of code ``code`` takes to
-                  run
-              * ``%config``:
-                  Configuration of the IPython Notebook
-              * ``%lsmagic``:
-                  Provides a list of all available magic commands
-            Cell magics
-            ~~~~~~~~~~~
-              * ``%%latex``:
-                  Renders the entire contents of the cell in LaTeX, without needing to use
-                  explicit LaTeX delimiters.
-              * ``%%bash``:
-                  The code cell is executed by sending it to be executed by ``bash``. The
-                  output of the ``bash`` commands is captured and displayed in the
-                  notebook.
-              * ``%%file filename``:
-                  Writes the contents of the cell to the file ``filename``.
-                  **Caution**: The file is over-written without warning!
-              * ``%%R``:
-                  Execute the contents of the cell using the R language.
-              * ``%%timeit``:
-                  Version of ``%timeit`` which times the entire block of code in the
-                  current code cell.
-            Several of the cell magics provide functionality to manipulate the filesystem
-            of a remote server to which you otherwise do not have access.
             Plotting
             --------
-            One major feature of the Notebook is the ability to interact with
+            One major feature of the notebook is the ability to display plots that are the
-            plots that are the output of running code cells. IPython is designed to work
+            output of running code cells. IPython is designed to work seamlessly with the
-            seamlessly with the ``matplotlib`` plotting library to provide this
+            matplotlib_ plotting library to provide this functionality.
-            functionality.
             To set this up, before any plotting is performed you must execute the
-            ``%matplotlib`` magic command. This performs the necessary behind-the-scenes
+            ``%matplotlib``  :ref:`magic command <magics_explained>`. This performs the
-            setup for IPython to work correctly hand in hand with ``matplotlib``; it does
+            necessary behind-the-scenes setup for IPython to work correctly hand in hand
-            *not*, however, actually execute any Python ``import`` commands, that is, no
+            with ``matplotlib``; it does *not*, however, actually execute any Python
-            names are added to the namespace.
+            ``import`` commands, that is, no names are added to the namespace.
             If the ``%matplotlib`` magic is called without an argument, the
             output of a plotting command is displayed using the default ``matplotlib``
             backend in a separate window. Alternatively, the backend can be explicitly
             requested using, for example::
               %matplotlib gtk
-            A particularly interesting backend is the ``inline`` backend.
+            A particularly interesting backend, provided by IPython, is the ``inline``
-            This is applicable only for the IPython Notebook and the IPython QtConsole.
+            backend.  This is available only for the IPython Notebook and the
-            It can be invoked as follows::
+            :ref:`IPython QtConsole <qtconsole>`.  It can be invoked as follows::
               %matplotlib inline
-            With this backend, output of plotting commands is displayed *inline* within
+            With this backend, the output of plotting commands is displayed *inline*
-            the notebook format, directly below the input cell that produced it. The
+            within the notebook, directly below the code cell that produced it. The
-            resulting plots will then also be stored in the notebook document. This
+            resulting plots will then also be stored in the notebook document.
-            provides a key part of the functionality for reproducibility_ that the IPython
-            Notebook provides.
-            .. _reproducibility: https://en.wikipedia.org/wiki/Reproducibility
+            .. seealso::
+                `Plotting with Matplotlib`_  example notebook
             Configuring the IPython Notebook
             --------------------------------
-            The IPython Notebook can be run with a variety of command line arguments.
+            The notebook server can be run with a variety of command line arguments.
             To see a list of available options enter::
               $ ipython notebook --help
             Defaults for these options can also be set by creating a file named
             ``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
             folder is a subfolder of your IPython directory; to find out where it is
             located, run::
               $ ipython locate
             To create a new set of default configuration files, with lots of information
             on available options, use::
               $ ipython profile create
             .. seealso::
                 :ref:`config_overview`, in particular :ref:`Profiles`.
+                :ref:`notebook_security`
+                :ref:`notebook_public_server`
             Importing ``.py`` files
             -----------------------
-            ``.py`` files will be imported into the IPython Notebook as a notebook with
+            ``.py`` files will be imported as a notebook with
             the same basename, but an ``.ipynb`` extension, located in the notebook
             directory. The notebook created will have just one cell, which will contain
             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.
             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.
+            script back into a notebook will preserve this structure.
+            .. _note_about_roundtrip:
             .. warning::
-               You can "roundtrip" a notebook to Python, by exporting the
+               While in simple cases you can "roundtrip" a notebook to Python, edit the
-               notebook to a ``.py`` script, editing the script, and then importing it back
+               Python file, and then import it back without loss of main content, this is
-               into the Notebook without loss of main content. However,
+               in general *not guaranteed to work*.  First, there is extra metadata
-               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.  And as
-               saved in the notebook that may not be saved to the ``.py`` format.  Second,
+               the notebook format evolves in complexity, there will be attributes of the
-               as the notebook format evolves in complexity, there will be attributes of
+               notebook that will not survive a roundtrip through the Python form.  You
-               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`
+            .. include:: ../links.txt

docs/source/interactive/public_server.rst ~~docs/source/interactive/working_remotely.rst~~

0 renamed +19 -42

             .. _working_remotely.txt
-            Working remotely
+            Running a notebook server
-            ================
+            =========================
-            The IPython Notebook web app is based on a server-client structure.
+            The  :ref:`IPython notebook <htmlnotebook>` web-application is based on a
-            This server uses a two-process kernel architecture based on ZeroMQ_, as well
+            server-client structure.  This server uses a :ref:`two-process kernel
-            as Tornado_ for serving HTTP requests. Other clients may connect to the same
+            architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
-            underlying IPython kernel; see below.
+            HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
+            and is accessible only from `localhost`. This document describes how you can
+            :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
+            a public interface <notebook_public_server>`.
             .. _ZeroMQ: http://zeromq.org
             .. _Tornado: http://www.tornadoweb.org
             .. _notebook_security:
-            Security
+            Notebook security
-            --------
+            -----------------
-            You can protect your Notebook server with a simple single password by
+            You can protect your notebook server with a simple single password by
             setting the :attr:`NotebookApp.password` configurable. You can prepare a
             hashed password using the function :func:`IPython.lib.security.passwd`:
             .. sourcecode:: ipython
                 In [1]: from IPython.lib import passwd
                 In [2]: passwd()
                 Enter password:
                 Verify password:
                 Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
             .. note::
               :func:`~IPython.lib.security.passwd` can also take the password as a string
               argument. **Do not** pass it as an argument inside an IPython session, as it
               will be saved in your input history.
             You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
                 # Password to use for web authentication
                 c = get_config()
                 c.NotebookApp.password =
                 u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
             When using a password, it is a good idea to also use SSL, so that your
             password is not sent unencrypted by your browser. You can start the notebook
             to communicate via a secure protocol mode using a self-signed certificate with
             the command::
                 $ ipython notebook --certfile=mycert.pem
             .. note::
                 A self-signed certificate can be generated with ``openssl``.  For example,
                 the following command will create a certificate valid for 365 days with
                 both the key and certificate data written to the same file::
                     $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.
                     pem -out mycert.pem
             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 detail in `this tutorial`__.
-            .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-
+            .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
-            secure-sertificate-for-free.ars
             Keep in mind that when you enable SSL support, you will need to access the
             notebook server over ``https://``, not over plain ``http://``.  The startup
             message from the server prints this, but it is easy to overlook and think the
             server is for some reason non-responsive.
-            Connecting to an existing kernel
+            .. _notebook_public_server:
-            ---------------------------------
-            The notebook server always prints to the terminal the full details of
-            how to connect to each kernel, with messages such as the following::
-                [IPKernelApp] To connect another client to this kernel, use:
-                [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
-            This long string is the name of a JSON file that contains all the port and
-            validation information necessary to connect to the kernel.  You can then, for
-            example, manually start a Qt console connected to the *same* kernel with::
-                $ ipython qtconsole --existing
-                kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
-            If you have only a single kernel running, simply typing::
-                $ ipython qtconsole --existing
-            will automatically find it. (It will always find the most recently
-            started kernel if there is more than one.)  You can also request this
-            connection data by typing ``%connect_info``; this will print the same
-            file information as well as the content of the JSON data structure it
-            contains.
             Running a public notebook server
             --------------------------------
             If you want to access your notebook server remotely via a web browser,
             you can do the following.
             Start by creating a certificate file and a hashed password, as explained
             above.  Then create a custom profile for the notebook, with the following
             command line, type::
               $ ipython profile create nbserver
             In the profile directory just created, edit the file
             ``ipython_notebook_config.py``.  By default, the file has all fields
             commented; the minimum set you need to uncomment and edit is the following::
                  c = get_config()
                  # Kernel config
                  c.IPKernelApp.pylab = 'inline'  # if you want plotting support always
                  # Notebook config
                  c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
                  c.NotebookApp.ip = '*'
                  c.NotebookApp.open_browser = False
                  c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'
                  # It is a good idea to put it on a known, fixed port
                  c.NotebookApp.port = 9999
             You can then start the notebook and access it later by pointing your browser
             to ``https://your.host.com:9999`` with ``ipython notebook
             --profile=nbserver``.
             Running with a different URL prefix
             -----------------------------------
             The notebook dashboard (the landing page with an overview
             of the notebooks in your working directory) typically lives at the URL
             ``http://localhost:8888/``. If you prefer that it lives, together with the
             rest of the notebook, under a sub-directory,
             e.g. ``http://localhost:8888/ipython/``, you can do so with
             configuration options like the following (see above for instructions about
             modifying ``ipython_notebook_config.py``)::
                 c.NotebookApp.base_project_url = '/ipython/'
                 c.NotebookApp.base_kernel_url = '/ipython/'
                 c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
             Using a different notebook store
             --------------------------------
-            By default, the Notebook app stores the notebook documents that it saves as
+            By default, the notebook server stores the notebook documents that it saves as
-            files in the working directory of the Notebook app, also known as the
+            files in the working directory of the notebook server, also known as the
             ``notebook_dir``. This  logic is implemented in the
             :class:`FileNotebookManager` class. However, the server can be configured to
             use a different notebook manager class, which can
             store the notebooks in a different format.
             Currently, we ship a :class:`AzureNotebookManager` class that stores notebooks
             in Azure blob storage. This can be used by adding the following lines to your
             ``ipython_notebook_config.py`` file::
                 c.NotebookApp.notebook_manager_class =
                 'IPython.html.services.notebooks.azurenbmanager.AzureNotebookManager'
                 c.AzureNotebookManager.account_name = u'paste_your_account_name_here'
                 c.AzureNotebookManager.account_key = u'paste_your_account_key_here'
                 c.AzureNotebookManager.container = u'notebooks'
             In addition to providing your Azure Blob Storage account name and key, you
             will have to provide a container name; you can use multiple containers to
             organize your notebooks.
             Known issues
             ------------
             When behind a proxy, especially if your system or browser is set to autodetect
-            the proxy, the Notebook app might fail to connect to the server's websockets,
+            the proxy, the notebook web application might fail to connect to the server's
-            and present you with a warning at startup. In this case, you need to configure
+            websockets, and present you with a warning at startup. In this case, you need
-            your system not to use the proxy for the server's address.
+            to configure your system not to use the proxy for the server's address.
             For example, in Firefox, go to the Preferences panel, Advanced section,
             Network tab, click 'Settings...', and add the address of the notebook server
             to the 'No proxy for' field.

docs/source/interactive/tutorial.rst

0 +50 -27

             .. _tutorial:
             ======================
             Introducing IPython
             ======================
             You don't need to know anything beyond Python to start using IPython – just type
             commands as you would at the standard Python prompt. But IPython can do much
             more than the standard prompt. Some key features are described here. For more
             information, check the :ref:`tips page <tips>`, or look at examples in the
-            `IPython cookbook <http://wiki.ipython.org/index.php?title=Cookbook>`_.
+            `IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
             If you've never used Python before, you might want to look at `the official
             tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
             Python <http://diveintopython.org/toc/index.html>`_.
+            The four most helpful commands
+            ===============================
+            The four most helpful commands, as well as their brief description, is shown
+            to you in a banner, every time you start IPython:
+            ==========    =========================================================
+            command       description
+            ==========    =========================================================
+            ?             Introduction and overview of IPython's features.
+            %quickref     Quick reference.
+            help          Python's own help system.
+            object?       Details about 'object', use 'object??' for extra details.
+            ==========    =========================================================
             Tab completion
             ==============
             Tab completion, especially for attributes, is a convenient way to explore the
             structure of any object you're dealing with. Simply type ``object_name.<TAB>``
             to view the object's attributes (see :ref:`the readline section <readline>` for
             more). Besides Python objects and keywords, tab completion also works on file
             and directory names.
             Exploring your objects
             ======================
             Typing ``object_name?`` will print all sorts of details about any object,
             including docstrings, function definition lines (for call arguments) and
             constructor details for classes. To get specific information on an object, you
             can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
+            .. _magics_explained:
             Magic functions
             ===============
             IPython has a set of predefined 'magic functions' that you can call with a
             command line style syntax.  There are two kinds of magics, line-oriented and
-            cell-oriented.  Line magics are prefixed with the ``%`` character and work much
+            cell-oriented.  **Line magics** are prefixed with the ``%`` character and work much
             like OS command-line calls: they get as an argument the rest of the line, where
-            arguments are passed without parentheses or quotes.  Cell magics are prefixed
+            arguments are passed without parentheses or quotes.  **Cell magics** are
-            with a double ``%%``, and they are functions that get as an argument not only
+            prefixed with a double ``%%``, and they are functions that get as an argument
-            the rest of the line, but also the lines below it in a separate argument.
+            not only the rest of the line, but also the lines below it in a separate
+            argument.
             The following examples show how to call the builtin ``timeit`` magic, both in
             line and cell mode::
                   In [1]: %timeit range(1000)
 loops, best of 3: 7.76 us per loop
                   In [2]: %%timeit x = range(10000)
             	 ...: max(x)
             	 ...:
 loops, best of 3: 223 us per loop
             The builtin magics include:
             - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
               ``%recall``, etc.
             - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
-              etc.
+              ``%automagic``, etc.
-            - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
+            - Other functions such as ``%reset``, ``%timeit``, ``%%file``, ``%load``, or
+              ``%paste``.
-            You can always call them using the % prefix, and if you're calling a line magic
+            You can always call them using the ``%`` prefix, and if you're calling a line
-            on a line by itself, you can omit even that (cell magics must always have the
+            magic on a line by itself, you can omit even that::
-            ``%%`` prefix)::
                 run thescript.py
+            You can toggle this behavior by running the ``%automagic`` magic.  Cell magics
+            must always have the ``%%`` prefix.
             A more detailed explanation of the magic system can be obtained by calling
             ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
             read its docstring. To see all the available magic functions, call
             ``%lsmagic``.
+            .. seealso::
+                `Cell magics`_ example notebook
             Running and Editing
             -------------------
-            The %run magic command allows you to run any python script and load all of its
+            The ``%run`` magic command allows you to run any python script and load all of
-            data directly into the interactive namespace. Since the file is re-read from
+            its data directly into the interactive namespace. Since the file is re-read
-            disk each time, changes you make to it are reflected immediately (unlike
+            from disk each time, changes you make to it are reflected immediately (unlike
-            imported modules, which have to be specifically reloaded). IPython also includes
+            imported modules, which have to be specifically reloaded). IPython also
-            :ref:`dreload <dreload>`, a recursive reload function.
+            includes :ref:`dreload <dreload>`, a recursive reload function.
-            %run has special flags for timing the execution of your scripts (-t), or for
+            ``%run`` has special flags for timing the execution of your scripts (-t), or
-            running them under the control of either Python's pdb debugger (-d) or
+            for running them under the control of either Python's pdb debugger (-d) or
             profiler (-p).
-            The %edit command gives a reasonable approximation of multiline editing,
+            The ``%edit`` command gives a reasonable approximation of multiline editing,
             by invoking your favorite editor on the spot. IPython will execute the
             code you type in there as if it were typed interactively.
             Debugging
             ---------
             After an exception occurs, you can call ``%debug`` to jump into the Python
             debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``,
             IPython will automatically start the debugger on any uncaught exception. You can
             print variables, see code, execute statements and even walk up and down the
             call stack to track down the true source of the problem. This can be an efficient
             way to develop and debug code, in many cases eliminating the need for print
             statements or external debugging tools.
             You can also step through a program from the beginning by calling
             ``%run -d theprogram.py``.
             History
             =======
             IPython stores both the commands you enter, and the results it produces. You
             can easily go through previous commands with the up- and down-arrow keys, or
             access your history in more sophisticated ways.
             Input and output history are kept in variables called ``In`` and ``Out``, keyed
             by the prompt numbers, e.g. ``In[4]``. The last three objects in output history
             are also kept in variables named ``_``, ``__`` and ``___``.
             You can use the ``%history`` magic function to examine past input and output.
             Input history from previous sessions is saved in a database, and IPython can be
             configured to save output history.
             Several other magic functions can use your input history, including ``%edit``,
             ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
             standard format to refer to lines::
                 %pastebin 3 18-20 ~1/1-5
             This will take line 3 and lines 18 to 20 from the current session, and lines
 -5 from the previous session.
             System shell commands
             =====================
             To run any command at the system shell, simply prefix it with !, e.g.::
                 !ping www.bbc.co.uk
             You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
             the values of Python variables or expressions to system commands, prefix them
             with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section
             <system_shell_access>` for more details.
             Define your own system aliases
             ------------------------------
             It's convenient to have aliases to the system commands you use most often.
             This allows you to work seamlessly from inside IPython with the same commands
             you are used to in your system shell. IPython comes with some pre-defined
             aliases and a complete system for changing directories, both via a stack (see
             %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
             visited directories and allows you to go to any previously visited one.
             Configuration
             =============
-            Much of IPython can be tweaked through configuration. To get started, use the
+            Much of IPython can be tweaked through :ref:`configuration <config_overview>`.
-            command ``ipython profile create`` to produce the default config files. These
+            To get started, use the command ``ipython profile create`` to produce the
-            will be placed in :file:`~/.ipython/profile_default` or
+            default config files. These will be placed in
-            :file:`~/.config/ipython/profile_default`, and contain comments explaining what
+            :file:`~/.ipython/profile_default` or
-            the various options do.
+            :file:`~/.config/ipython/profile_default`, and contain comments explaining
+            what the various options do.
             Profiles allow you to use IPython for different tasks, keeping separate config
             files and history for each one. More details in :ref:`the profiles section
             <profiles>`.
             Startup Files
             -------------
             If you want some code to be run at the beginning of every IPython session, the
             easiest way is to add Python (.py) or IPython (.ipy) scripts to your
             :file:`profile_default/startup/` directory. Files here will be executed as soon
             as the IPython shell is constructed, before any other code or scripts you have
             specified. The files will be run in order of their names, so you can control the
             ordering with prefixes, like ``10-myimports.py``.
-            .. note::
+            .. include:: ../links.txt
-                Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
-                in :file:`ipython_config.py` for similar behavior in 0.11.

docs/source/links.txt

0 +28 -2

             .. This (-*- rst -*-) format file contains commonly used link targets
                and name substitutions.  It may be included in many files,
                therefore it should only contain link targets and name
                substitutions.  Try grepping for "^\.\. _" to find plausible
                candidates for this list.
                NOTE: this file must have an extension *opposite* to that of the main reST
                files in the manuals, so that we can include it with ".. include::"
                directives, but without triggering warnings from Sphinx for not being listed
                in any toctree.  Since IPython uses .txt for the main files, this wone will
                use .rst.
                NOTE: reST targets are
                __not_case_sensitive__, so only one target definition is needed for
                ipython, IPython, etc.
                NOTE: Some of these were taken from the nipy links compendium.
             .. Main IPython links
             .. _ipython: http://ipython.org
             .. _`ipython manual`: http://ipython.org/documentation.html
             .. _ipython_github: http://github.com/ipython/ipython/
             .. _ipython_github_repo: http://github.com/ipython/ipython/
             .. _ipython_downloads: http://ipython.org/download.html
             .. _ipython_pypi: http://pypi.python.org/pypi/ipython
+            .. _nbviewer: http://nbviewer.ipython.org
             .. _ZeroMQ: http://zeromq.org
             .. Documentation tools and related links
             .. _graphviz: http://www.graphviz.org
             .. _Sphinx: http://sphinx.pocoo.org
             .. _`Sphinx reST`: http://sphinx.pocoo.org/rest.html
             .. _sampledoc: http://matplotlib.sourceforge.net/sampledoc
             .. _reST: http://docutils.sourceforge.net/rst.html
             .. _docutils: http://docutils.sourceforge.net
             .. _lyx: http://www.lyx.org
             .. _pep8: http://www.python.org/dev/peps/pep-0008
             .. _numpy_coding_guide: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
             .. Licenses
             .. _GPL: http://www.gnu.org/licenses/gpl.html
             .. _BSD: http://www.opensource.org/licenses/bsd-license.php
             .. _LGPL: http://www.gnu.org/copyleft/lesser.html
             .. Other python projects
             .. _numpy: http://numpy.scipy.org
             .. _scipy: http://www.scipy.org
             .. _scipy_conference: http://conference.scipy.org
-            .. _matplotlib: http://matplotlib.sourceforge.net
+            .. _matplotlib: http://matplotlib.org
             .. _pythonxy: http://www.pythonxy.com
             .. _ETS: http://code.enthought.com/projects/tool-suite.php
             .. _EPD: http://www.enthought.com/products/epd.php
             .. _python: http://www.python.org
             .. _mayavi: http://code.enthought.com/projects/mayavi
             .. _sympy: http://code.google.com/p/sympy
             .. _sage: http://sagemath.org
             .. _pydy: http://code.google.com/p/pydy
             .. _vpython: http://vpython.org
             .. _cython: http://cython.org
             .. _software carpentry: http://software-carpentry.org
             .. Not so python scientific computing tools
             .. _matlab: http://www.mathworks.com
             .. _VTK: http://vtk.org
             .. Other organizations
             .. _enthought: http://www.enthought.com
             .. _kitware: http://www.kitware.com
             .. _netlib: http://netlib.org
             .. Other tools and projects
             .. _indefero: http://www.indefero.net
             .. _git: http://git-scm.com
             .. _github: http://github.com
-            .. _MarkDown: http://daringfireball.net/projects/markdown/
+            .. _Markdown: http://daringfireball.net/projects/markdown/syntax
+            .. _Running Code in the IPython Notebook: notebook_p1_
+            .. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
+            .. _Basic Output: notebook_p2_
+            .. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
+            .. _Plotting with Matplotlib: notebook_p3_
+            .. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
+            .. _Markdown Cells: notebook_p4
+            .. _notebook_p4: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb
+            .. _Rich Display System: notebook_p5_
+            .. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
+            .. _notebook_custom_display: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Custom%20Display%20Logic.ipynb
+            .. _Frontend/Kernel Model: notebook_two_proc_
+            .. _notebook_two_proc: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Frontend-Kernel%20Model.ipynb
+            .. _Cell magics: notebook_cell_magics_
+            .. _notebook_cell_magics: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Cell%20Magics.ipynb

docs/source/overview.rst

0 +9 -4

             .. _overview:
             ============
             Introduction
             ============
             Overview
             ========
             One of Python's most useful features is its interactive interpreter.
             It allows for very fast testing of ideas without the overhead of
             creating test files as is typical in most programming languages.
             However, the interpreter supplied with the standard Python distribution
             is somewhat limited for extended interactive use.
             The goal of IPython is to create a comprehensive environment for
             interactive and exploratory computing.  To support this goal, IPython
             has three main components:
             * An enhanced interactive Python shell.
-            * A decoupled two-process communication model, which allows for multiple
+            * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
-              clients to connect to a computation kernel, most notably the web-based
+              allows for multiple clients to connect to a computation kernel, most notably
-              :ref:`notebook <htmlnotebook>`
+              the web-based :ref:`notebook <htmlnotebook>`
             * An architecture for interactive parallel computing.
             All of IPython is open source (released under the revised BSD license).
             Enhanced interactive Python shell
             =================================
             IPython's interactive shell (:command:`ipython`), has the following goals,
             amongst others:
 . Provide an interactive shell superior to Python's default. IPython
                has many features for tab-completion, object introspection, system shell
                access, command history retrieval across sessions, and its own special
                command system for adding functionality when working interactively. It
                tries to be a very efficient environment both for Python code development
                and for exploration of problems using Python objects (in situations like
                data analysis).
 . Serve as an embeddable, ready to use interpreter for your own
                programs. An interactive IPython shell can be started with a single call
                from inside another program, providing access to the current namespace.
                This can be very useful both for debugging purposes and for situations
                where a blend of batch-processing and interactive exploration are needed.
 . Offer a flexible framework which can be used as the base
                environment for working with other systems, with Python as the underlying
                bridge language. Specifically scientific environments like Mathematica,
                IDL and Matlab inspired its design, but similar ideas can be
                useful in many fields.
 . Allow interactive testing of threaded graphical toolkits. IPython
                has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and
                OS X applications via special threading flags. The normal Python
                shell can only do this for Tkinter applications.
             Main features of the interactive shell
             --------------------------------------
             * Dynamic object introspection. One can access docstrings, function
               definition prototypes, source code, source files and other details
               of any object accessible to the interpreter with a single
               keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
             * Searching through modules and namespaces with :samp:`*` wildcards, both
               when using the :samp:`?` system and via the :samp:`%psearch` command.
             * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
               This works for keywords, modules, methods, variables and files in the
               current directory. This is supported via the readline library, and
               full access to configuring readline's behavior is provided.
               Custom completers can be implemented easily for different purposes
               (system commands, magic arguments etc.)
             * Numbered input/output prompts with command history (persistent
               across sessions and tied to each profile), full searching in this
               history and caching of all input and output.
             * User-extensible 'magic' commands. A set of commands prefixed with
               :samp:`%` is available for controlling IPython itself and provides
               directory control, namespace information and many aliases to
               common system shell commands.
             * Alias facility for defining your own system aliases.
             * Complete system shell access. Lines starting with :samp:`!` are passed
               directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd`
               captures shell output into python variables for further use.
             * The ability to expand python variables when calling the system shell. In a
               shell command, any python variable prefixed with :samp:`$` is expanded. A
               double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access
               to shell and environment variables like :envvar:`PATH`).
             * Filesystem navigation, via a magic :samp:`%cd` command, along with a
               persistent bookmark system (using :samp:`%bookmark`) for fast access to
               frequently visited directories.
             * A lightweight persistence framework via the :samp:`%store` command, which
               allows you to save arbitrary Python variables. These get restored
               when you run the :samp:`%store -r` command.
             * Automatic indentation (optional) of code as you type (through the
               readline library).
             * Macro system for quickly re-executing multiple lines of previous
               input with a single name via the :samp:`%macro` command. Macros can be
               stored persistently via :samp:`%store` and edited via :samp:`%edit`.
             * Session logging (you can then later use these logs as code in your
               programs). Logs can optionally timestamp all input, and also store
               session output (marked as comments, so the log remains valid
               Python source code).
             * Session restoring: logs can be replayed to restore a previous
               session to the state where you left it.
             * Verbose and colored exception traceback printouts. Easier to parse
               visually, and in verbose mode they produce a lot of useful
               debugging information (basically a terminal version of the cgitb
               module).
             * Auto-parentheses via the :samp:`%autocall` command: callable objects can be
               executed without parentheses: :samp:`sin 3` is automatically converted to
               :samp:`sin(3)`
             * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
               auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
               automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
               becomes :samp:`my_function("a b")`.
             * Extensible input syntax. You can define filters that pre-process
               user input to simplify input in special situations. This allows
               for example pasting multi-line code fragments which start with
               :samp:`>>>` or :samp:`...` such as those from other python sessions or the
               standard Python documentation.
             * Flexible :ref:`configuration system <config_overview>`. It uses a
               configuration file which allows permanent setting of all command-line
               options, module loading, code and file execution. The system allows
               recursive file inclusion, so you can have a base file with defaults and
               layers which load other customizations for particular projects.
             * Embeddable. You can call IPython as a python shell inside your own
               python programs. This can be used both for debugging code or for
               providing interactive abilities to your programs with knowledge
               about the local namespaces (very useful in debugging and data
               analysis situations).
             * Easy debugger access. You can set IPython to call up an enhanced version of
               the Python debugger (pdb) every time there is an uncaught exception. This
               drops you inside the code which triggered the exception with all the data
               live and it is possible to navigate the stack to rapidly isolate the source
               of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run
               any script under pdb's control, automatically setting initial breakpoints for
               you.  This version of pdb has IPython-specific improvements, including
               tab-completion and traceback coloring support. For even easier debugger
               access, try :samp:`%debug` after seeing an exception.
             * Profiler support. You can run single statements (similar to
               :samp:`profile.run()`) or complete programs under the profiler's control.
               While this is possible with standard cProfile or profile modules,
               IPython wraps this functionality with magic commands (see :samp:`%prun`
               and :samp:`%run -p`) convenient for rapid interactive work.
             * Simple timing information. You can use the :samp:`%timeit` command to get
               the execution time of a Python statement or expression. This machinery is
               intelligent enough to do more repetitions for commands that finish very
               quickly in order to get a better estimate of their running time.
             .. sourcecode:: ipython
                 In [1]: %timeit 1+1
                 10000000 loops, best of 3: 25.5 ns per loop
                 In [2]: %timeit [math.sin(x) for x in range(5000)]
 loops, best of 3: 719 µs per loop
             ..
               To get the timing information for more than one expression, use the
               :samp:`%%timeit` cell magic command.
             * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
               to use doctest-compatible prompts, so you can use IPython sessions as
               doctest code. By default, IPython also allows you to paste existing
               doctests, and strips out the leading :samp:`>>>` and :samp:`...` prompts in
               them.
             .. _ipythonzmq:
             Decoupled two-process model
             ==============================
             IPython has abstracted and extended the notion of a traditional
             *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation*
-            into its own process. We call this process a kernel: it receives execution
+            into its own process. We call this process a **kernel**: it receives execution
             instructions from clients and communicates the results back to them.
             This decoupling allows us to have several clients connected to the same
             kernel, and even allows clients and kernels to live on different machines.
             With the exclusion of the traditional single process terminal-based IPython
             (what you start if you run ``ipython`` without any subcommands), all
             other IPython machinery uses this two-process model. This includes ``ipython
             console``,  ``ipython qtconsole``, and ``ipython notebook``.
             As an example, this means that when you start ``ipython qtconsole``, you're
             really starting two processes, a kernel and a Qt-based client can send
             commands to and receive results from that kernel. If there is already a kernel
             running that you want to connect to, you can pass the  ``--existing`` flag
             which will skip initiating a new kernel and connect to the most recent kernel,
             instead. To connect to a specific kernel once you have several kernels
             running, use the ``%connect_info`` magic to get the unique connection file,
             which will be something like ``--existing kernel-19732.json`` but with
             different numbers which correspond to the Process ID of the kernel.
             You can read more about using :ref:`ipython qtconsole <qtconsole>`, and
             :ref:`ipython notebook <htmlnotebook>`. There is also a :ref:`message spec
             <messaging>` which documents the protocol for communication between kernels
             and clients.
+            .. seealso::
+                `Frontend/Kernel Model`_ example notebook
             Interactive parallel computing
             ==============================
             Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
             supercomputers, is becoming ubiquitous. Over the last several years, we have
             developed an architecture within IPython that allows such hardware to be used
             quickly and easily from Python. Moreover, this architecture is designed to
             support interactive and collaborative parallel computing.
             The main features of this system are:
             * Quickly parallelize Python code from an interactive Python/IPython session.
             * A flexible and dynamic process model that be deployed on anything from
               multicore workstations to supercomputers.
             * An architecture that supports many different styles of parallelism, from
               message passing to task farming.  And all of these styles can be handled
               interactively.
             * Both blocking and fully asynchronous interfaces.
             * High level APIs that enable many things to be parallelized in a few lines
               of code.
             * Write parallel code that will run unchanged on everything from multicore
               workstations to supercomputers.
             * Full integration with Message Passing libraries (MPI).
             * Capabilities based security model with full encryption of network connections.
             * Share live parallel jobs with other users securely.  We call this
               collaborative parallel computing.
             * Dynamically load balanced task farming system.
             * Robust error handling.  Python exceptions raised in parallel execution are
               gathered and presented to the top-level code.
             For more information, see our :ref:`overview <parallel_index>` of using IPython
             for parallel computing.
             Portability and Python requirements
             -----------------------------------
             As of the 1.0 release, IPython works with Python 2.6, 2.7, 3.2 and 3.3.
             Version 0.12 introduced full support for Python 3. Version 0.11 worked with
             Python 2.6 and 2.7 only. Versions 0.9 and 0.10 worked with Python 2.4 and
             above (not including Python 3).
             IPython is known to work on the following operating systems:
             	* Linux
             	* Most other Unix-like OSs (AIX, Solaris, BSD, etc.)
             	* Mac OS X
             	* Windows (CygWin, XP, Vista, etc.)
             See :ref:`here <install_index>` for instructions on how to install IPython.
+            .. include:: links.txt

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages