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 b''
	1	<html>
	2	<head>
	3	<meta http-equiv="Refresh" content="0; url=notebook.html" />
	4	<title>Notebook page has move</title>
	5	</head>
	6	<body>
	7	<p>The notebook page has moved to <a href="notebook.html">this link</a>.</p>
	8	</body>
	9	</html>

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 +225 -323

This diff has been collapsed as it changes many lines, (548 lines changed) Show them Hide them
	@@ -1,590 +1,492 b''
	1	.. _htmlnotebook:	1	.. _htmlnotebook:
	2		2
	3	The IPython Notebook	3	The IPython Notebook
	4	====================	4	====================
	5		5
	6	The IPython Notebook is part of the IPython package, which aims to provide a	6	Introduction
	7	powerful, interactive approach to scientific computation.	7	------------
	8	The IPython Notebook extends the previous text-console-based approach, and the
	9	later Qt console, in a qualitatively new diretion, providing a web-based
	10	application suitable for capturing the whole scientific computation process.
	11		8
	12	.. seealso::	9	The notebook extends the console-based approach to interactive computing in
			10	a qualitatively new direction, providing a web-based application suitable for
			11	capturing the whole computation process: developing, documenting, and
			12	executing code, as well as communicating the results. The IPython notebook
			13	combines two components:
	13		14
	14	:ref:`Installation requirements <installnotebook>` for the Notebook.	15	A web application: a browser-based tool for interactive authoring of
			16	documents which combine explanatory text, mathematics, computations and their
			17	rich media output.
	15		18
			19	Notebook documents: a representation of all content visible in the web
			20	application, including inputs and outputs of the computations, explanatory
			21	text, mathematics, images, and rich media representations of objects.
	16		22
	17	.. Basic structure	23	.. seealso::
	18	.. ---------------
	19		24
	20	Introduction	25	See the :ref:`installation documentation <installnotebook>` for directions
	21	------------	26	on how to install the notebook and its dependencies.
	22		27
	23	The IPython Notebook combines two components:
	24		28
	25	* The IPython Notebook web application:	29	Main features of the web application
			30	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	26		31
	27	The IPython Notebook web app is a browser-based tool for interactive	32	* In-browser editing for code, with automatic syntax highlighting,
	28	authoring of literate computations, in which explanatory text,	33	indentation, and tab completion/introspection.
	29	mathematics, computations and rich media output may be combined. Input
	30	and output are stored in persistent cells that may be edited in-place.
	31		34
	32	* Notebook documents:	35	* The ability to execute code from the browser, with the results of
			36	computations attached to the code which generated them.
	33		37
	34	Notebook documents, or notebooks, are plain text documents which	38	* Displaying the result of computation using rich media representations, such
	35	record all inputs and outputs of the computations, interspersed with	39	as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
	36	text, mathematics and HTML 5 representations of objects, in a literate	40	rendered by the matplotlib_ library, can be included inline.
	37	style.
	38		41
	39	Since the similarity in names can lead to some confusion, in this	42	* In-browser editing for rich text using the Markdown_ markup language, which
	40	documentation we will use capitalization of the word "notebook" to	43	can provide commentary for the code, is not limited to plain text.
	41	distinguish the Notebook app and notebook documents, thinking of the
	42	Notebook app as being a proper noun. We will also always refer to the
	43	"Notebook app" when we are referring to the browser-based interface,
	44	and usually to "notebook documents", instead of "notebooks", for added
	45	precision.
	46		44
	47	We refer to the current state of the computational process taking place in the	45	* The ability to easily include mathematical notation within markdown cells
	48	Notebook app, i.e. the (numbered) sequence of input and output cells, as the	46	using LaTeX, and rendered natively by MathJax_.
	49	notebook space. Notebook documents provide an exact, one-to-one record
	50	of all the content in the notebook space, as a plain text file in JSON format.
	51	The Notebook app automatically saves, at certain intervals, the contents of
	52	the notebook space to a notebook document stored on disk, with the same name
	53	as the title of the notebook space, and the file extension ``.ipynb``. For
	54	this reason, there is no confusion about using the same word "notebook" for
	55	both the notebook space and the corresponding notebook document, since they are
	56	really one and the same concept (we could say that they are "isomorphic").
	57		47
	58		48
	59	Main features of the IPython Notebook web app
	60	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	61		49
	62	The main features of the IPython Notebook app include:	50	.. _MathJax: http://www.mathjax.org/
	63		51
	64	* In-browser editing for code, with automatic syntax highlighting and
	65	indentation and tab completion/introspection.
	66		52
	67	* Literate combination of code with rich text using the Markdown_ markup	53	Notebook documents
	68	language.	54	~~~~~~~~~~~~~~~~~~
			55	Notebook documents contains the inputs and outputs of a interactive session as
			56	well as additional text that accompanies the code but is not meant for
			57	execution. In this way, notebook files can serve as a complete computational
			58	record of a session, interleaving executable code with explanatory text,
			59	mathematics, and rich representations of resulting objects. These documents
			60	are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
			61	JSON is a plain text format, they can be version-controlled and shared with
			62	colleagues.
			63
			64	.. _JSON: http://en.wikipedia.org/wiki/JSON
	69		65
	70	* Mathematics is easily included within the Markdown using LaTeX notation, and	66	Notebooks may be exported to a range of static formats, including HTML (for
	71	rendered natively by MathJax_.	67	example, for blog posts), reStructeredText, LaTeX, PDF, and slide shows, via
			68	the new :ref:`nbconvert <nbconvert>` command.
	72		69
	73	* Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result	70	Furthermore, any ``.ipynb`` notebook document available from a public
	74	of computations.	71	URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
			72	This service loads the notebook document from the URL and renders it as a
			73	static web page. The results may thus be shared with a colleague, or as a
			74	public blog post, without other users needing to install IPython themselves.
			75	In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
			76	so you can do your own static conversions with nbconvert, without relying on
			77	nbviewer.
	75		78
	76	* Publication-quality figures in a range of formats (SVG / PNG), rendered by
	77	the matplotlib_ library, may be included inline and exported.
	78		79
	79		80
	80	.. _MathJax: http://www.mathjax.org/	81	.. seealso::
	81	.. _matplotlib: http://matplotlib.org/
	82	.. _Markdown: http://daringfireball.net/projects/markdown/syntax
	83		82
			83	:ref:`Details on the notebook JSON file format <notebook_format>`
			84
	84		85
	85	Notebook documents	86	Starting the notebook server
	86	~~~~~~~~~~~~~~~~~~	87	----------------------------
	87		88
	88	Notebook document files are simple JSON_ files with the	89	You can start running a notebook server from the command line using the
	89	extension ``.ipynb``.	90	following command::
	90	Since JSON is just plain text, they can be easily version-controlled and shared with colleagues.
	91	The notebook stores a complete, reproducible, one-to-one copy of the state of the
	92	computational state as it is inside the Notebook app. All computations
	93	carried out, and the corresponding results obtained, can be combined in
	94	a literate way, interleaving executable code with rich text, mathematics,
	95	and rich representations of objects.
	96		91
	97	.. _JSON: http://en.wikipedia.org/wiki/JSON	92	ipython notebook
	98		93
	99	Notebooks may easily be exported to a range of static formats, including	94	This will print some information about the notebook server in your console,
	100	HTML (for example, for blog posts), PDF and slide shows,	95	and open a web browser to the URL of the web application (by default,
	101	via the new nbconvert_ command.	96	``http://127.0.0.1:8888``).
	102		97
	103	Furthermore, any ``.ipynb`` notebook document available from a public	98	The landing page of the IPython notebook web application, the dashboard,
	104	URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ service.	99	shows the notebooks currently available in the notebook directory (by default,
	105	This service loads the notebook document from the URL and renders	100	the directory from which the notebook server was started).
	106	it as a static web page. The results may thus be shared with a
	107	colleague, or as a public blog post, without other users needing to install
	108	IPython themselves. NbViewer is simply nbconvert_ as a simple webservice.
	109		101
	110	See the :ref:`installation documentation <install_index>` for directions on	102	You can create new notebooks from the dashboard with the ``New Notebook``
	111	how to install the notebook and its dependencies.	103	button, or open existing ones by clicking on their name. You can also drag
			104	and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
			105	into the notebook list area.
	112		106
	113	.. _nbconvert: ./nbconvert.html	107	When starting a notebook server from the command line, you can also open a
			108	particular notebook directly, bypassing the dashboard, with ``ipython notebook
			109	my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
			110	given.
			111
			112	When you are inside an open notebook, the `File \| Open...` menu option will
			113	open the dashboard in a new browser tab, to allow you to open another notebook
			114	from the notebook directory or to create a new notebook.
	114		115
	115	.. _nbviewer: http://nbviewer.ipython.org
	116		116
	117	.. note::	117	.. note::
	118		118
	119	You can start more than one notebook server at the same time, if you want	119	You can start more than one notebook server at the same time, if you want
	120	to work on notebooks in different directories. By default the first	120	to work on notebooks in different directories. By default the first
	121	notebook server starts on port 8888, and later notebook servers search for	121	notebook server starts on port 8888, and later notebook servers search for
	122	ports near that one. You can also manually specify the port with the	122	ports near that one. You can also manually specify the port with the
	123	``--port`` option.	123	``--port`` option.
	124
	125		124
	126	Basic workflow in the IPython Notebook web app	125	Creating a new notebook document
	127	----------------------------------------------	126	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	128		127
	129	Starting up	128	A new notebook may be created at any time, either from the dashboard, or using
	130	~~~~~~~~~~~~	129	the `File \| New` menu option from within an active notebook. The new notebook
			130	is created within the same directory and will open in a new browser tab. It
			131	will also be reflected as a new entry in the notebook list on the dashboard.
	131		132
	132	You can start running the Notebook web app using the following command::
	133		133
	134	$ ipython notebook	134	Opening notebooks
			135	~~~~~~~~~~~~~~~~~
			136	An open notebook has exactly one interactive session connected to an
			137	:ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
			138	and communicate back results. This kernel remains active if the web browser
			139	window is closed, and reopening the same notebook from the dashboard will
			140	reconnect the web application to the same kernel. In the dashboard, notebooks
			141	with an active kernel have a ``Shutdown`` button next to them, whereas
			142	notebooks without an active kernel have a ``Delete`` button in its place.
	135		143
	136	(Here, and in the sequel, the initial ``$`` represents the shell prompt,	144	Other clients may connect to the same underlying IPython kernel.
	137	indicating that the command is to be run from the command line in a shell.)	145	The notebook server always prints to the terminal the full details of
			146	how to connect to each kernel, with messages such as the following::
	138		147
	139	The landing page of the IPython Notebook application, the dashboard, shows	148	[NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
	140	the notebooks currently available in the notebook directory (By default, the directory
	141	from which the notebook was started).
	142	You can create new notebooks from the dashboard with the ``New Notebook``
	143	button, or open existing ones by clicking on their name.
	144	You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python
	145	source code files into the notebook list area.
	146		149
			150	This long string is the kernel's ID which is sufficient for getting the
			151	information necessary to connect to the kernel. You can also request this
			152	connection data by running the ``%connect_info`` :ref:`magic
			153	<magics_explained>`. This will print the same ID information as well as the
			154	content of the JSON data structure it contains.
	147		155
	148	You can open an existing notebook directly, without having to go via the	156	You can then, for example, manually start a Qt console connected to the same
	149	dashboard, with::	157	kernel from the command line, by passing a portion of the ID::
	150		158
	151	ipython notebook my_notebook	159	$ ipython qtconsole --existing 87f7d2c0
	152		160
	153	The ``.ipynb`` extension is assumed if no extension is given.	161	Without an ID, ``--existing`` will connect to the most recently
	154		162	started kernel. This can also be done by running the ``%qtconsole``
	155	The `File \| Open...` menu option will open the dashboard in a new browser tab,	163	:ref:`magic <magics_explained>` in the notebook.
	156	to allow you to select a current notebook
	157	from the notebook directory or to create a new notebook.
	158		164
			165	.. seealso::
	159		166
			167	:ref:`ipythonzmq`
	160		168
	161	Notebook user interface	169	Notebook user interface
	162	~~~~~~~~~~~~~~~~~~~~~~~	170	-----------------------
	163
	164	When you open a new notebook document in the Notebook, you will be presented
	165	with the title associated to the notebook space/document, a menu bar, a
	166	toolbar and an empty input cell.
	167		171
	168	Notebook title	172	When you create a new notebook document, you will be presented with the
	169	^^^^^^^^^^^^^^	173	notebook name, a menu bar, a toolbar and an empty **code
	170	The title of the notebook document that is currently being edited is displayed	174	cell**.
	171	at the top of the page, next to the ``IP[y]: Notebook`` logo. This title may
	172	be edited directly by clicking on it. The title is reflected in the name of
	173	the ``.ipynb`` notebook document file that is saved.
	174		175
	175	Menu bar	176	notebook name: The name of the notebook document is displayed at the top
	176	^^^^^^^^	177	of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
	177	The menu bar presents different options that may be used to manipulate the way	178	of the ``.ipynb`` notebook document file. Clicking on the notebook name
	178	the Notebook functions.	179	brings up a dialog which allows you to rename it. Thus, renaming a notebook
			180	from "Untitled0" to "My first notebook" in the browser, renames the
			181	``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
	179		182
	180	Toolbar	183	menu bar: The menu bar presents different options that may be used to
	181	^^^^^^^	184	manipulate the way the notebook functions.
	182	The tool bar gives a quick way of accessing the most-used operations within
	183	the Notebook, by clicking on an icon.
	184		185
			186	toolbar: The tool bar gives a quick way of performing the most-used
			187	operations within the notebook, by clicking on an icon.
	185		188
	186	Creating a new notebook document	189	code cell: the default type of cell, read on for an explanation of cells
	187	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	188
	189	A new notebook space/document may be created at any time, either from the
	190	dashboard, or using the `File \| New` menu option from within an active
	191	notebook. The new notebook is created within the same directory and
	192	will open in a new browser tab. It will also be reflected as a new entry in
	193	the notebook list on the dashboard.
	194		190
	195		191
	196	Structure of a notebook document	192	Structure of a notebook document
	197	--------------------------------	193	--------------------------------
	198		194
	199	Input cells	195	The notebook consists of a sequence of cells. A cell is a multi-line
	200	~~~~~~~~~~~	196	text input field, and its contents can be executed by using
	201	Input cells are at the core of the functionality of the IPython Notebook.	197	:kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
	202	They are regions in the document in which you can enter different types of	198	`Cell \| Run` in the menu bar. The execution behavior of a cell is determined
	203	text and commands. To execute or run the current cell, i.e. the cell	199	the cell's type. There are four types of cells: code cells, **markdown
	204	under the cursor, you can use the :kbd:`Shift-Enter` key combination.	200	cells, raw cells and heading cells**. Every cell starts off
	205	This tells the Notebook app to perform the relevant operation for each type of	201	being a code cell, but its type can be changed by using a dropdown on the
	206	cell (see below), and then to display the resulting output.	202	toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
	207		203	<keyboard-shortcuts>`.
	208	The notebook consists of a sequence of input cells, labelled ``In[n]``, which
	209	may be executed in a non-linear way, and outputs ``Out[n]``, where ``n`` is a
	210	number which denotes the order in which the cells were executed over the
	211	history of the computational process. The contents of all of these cells are
	212	accessible as Python variables with the same names, forming a complete record
	213	of the history of the computation.
	214
	215
	216
	217	Input cell types
	218	~~~~~~~~~~~~~~~~
	219	Each IPython input cell has a cell type, of which there is a restricted
	220	number. The type of a cell may be set by using the cell type dropdown on the
	221	toolbar, or via the following keyboard shortcuts:
	222
	223	* code: :kbd:`Ctrl-m y`
	224	* markdown: :kbd:`Ctrl-m m`
	225	* raw: :kbd:`Ctrl-m t`
	226	* heading: :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
	227
	228	Upon initial creation, each input cell is by default a code cell.
	229		204
	230		205
	231	Code cells	206	Code cells
	232	^^^^^^^^^^	207	~~~~~~~~~~
	233	A code ~~input~~ cell allows you to edit ~~code inline within the cell~~, with full	208	A code cell allows you to edit and write new code, with full syntax
	234	~~syntax~~ highlighting and ~~auto~~completion~~/introspection~~. By default, the language	209	highlighting and tab completion. By default, the language associated to a code
	235	~~associated to a code~~ cell is Python, but other languages, such as ``julia``	210	cell is Python, but other languages, such as ``Julia`` and ``R``, can be
	236	and ``R``, can be handled using magic commands (see below).	211	handled using :ref:`cell magic commands <magics_explained>`.
	237		212
	238	When a code cell is executed with :kbd:`Shift-Enter`, the code that it	213	When a code cell is executed, code that it contains is sent to the kernel
	239	contains is transparently exported and run in that language (with automatic	214	associated with the notebook. The results that are returned from this
	240	compiling, etc., if necessary). The result that is returned from this	215	computation are then displayed in the notebook as the cell's output. The
	241	computation is then displayed in the notebook space as the cell's	216	output is not limited to text, with many other possible forms of output are
	242	output. If this output is of a textual nature, it is placed into a	217	also possible, including ``matplotlib`` figures and HTML tables (as used, for
	243	numbered output cell. However, many other possible forms of output are also	218	example, in the ``pandas`` data analysis package). This is known as IPython's
	244	possible, including ``matplotlib`` figures and HTML tables (as used, for
	245	example, in the ``pandas`` data analyis package). This is known as IPython's
	246	rich display capability.	219	rich display capability.
	247		220
			221	.. seealso::
			222
			223	`Basic Output`_ example notebook
			224
			225	`Rich Display System`_ example notebook
	248		226
	249	Markdown cells	227	Markdown cells
	250	^^^^^^^^^^^^^^	228	~~~~~~~~~~~~~~
	251	You can document the computational process in a literate way, alternating	229	You can document the computational process in a literate way, alternating
	252	descriptive text with code, using rich text. In IPython this is accomplished	230	descriptive text with code, using rich text. In IPython this is accomplished
	253	by marking up text with the Markdown language. The corresponding cells are	231	by marking up text with the Markdown language. The corresponding cells are
	254	called Markdown ~~input~~ cells. The Markdown language provides a simple way to	232	called Markdown cells. The Markdown language provides a simple way to
	255	perform this text markup, that is, to specify which parts of the text should	233	perform this text markup, that is, to specify which parts of the text should
	256	be emphasized (italics), bold, form lists, etc.	234	be emphasized (italics), bold, form lists, etc.
	257		235
	258		236
	259	When a Markdown ~~input~~ cell is executed, the Markdown code is converted into	237	When a Markdown cell is executed, the Markdown code is converted into
	260	the corresponding formatted rich text. This output then replaces the	238	the corresponding formatted rich text. Markdown allows arbitrary HTML code for
	261	original Markdown input cell, leaving just the visually-significant marked up	239	formatting.
	262	rich text. Markdown allows arbitrary HTML code for formatting.
	263		240
	264	Within Markdown cells, you can also include mathematics in a straightforward	241	Within Markdown cells, you can also include mathematics in a straightforward
	265	way, using standard LaTeX notation: ``$...$`` for inline mathematics and	242	way, using standard LaTeX notation: ``$...$`` for inline mathematics and
	266	``$$...$$`` for displayed mathematics. When the Markdown cell is executed,	243	``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
	267	the LaTeX portions are automatically rendered in the HTML output as equations	244	the LaTeX portions are automatically rendered in the HTML output as equations
	268	with high quality typography. This is made possible by MathJax_, which	245	with high quality typography. This is made possible by MathJax_, which
	269	supports a `large subset <mathjax_tex>`_ of LaTeX functionality	246	supports a `large subset <mathjax_tex>`_ of LaTeX functionality
	270		247
	271	.. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html	248	.. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html
	272		249
	273	Standard mathematics environments defined by LaTeX and AMS-LaTeX (the	250	Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
	274	`amsmath` package) also work, such as	251	`amsmath` package) also work, such as
	275	``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.	252	``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
	276	New LaTeX macros may be defined using standard methods,	253	New LaTeX macros may be defined using standard methods,
	277	such as ``\newcommand``, by placing them anywhere between math delimiters in	254	such as ``\newcommand``, by placing them anywhere between math delimiters in
	278	a Markdown cell. These definitions are then available throughout the rest of	255	a Markdown cell. These definitions are then available throughout the rest of
	279	the IPython session. (Note, however, that more care must be taken when using	256	the IPython session.
	280	nbconvert_ to output to LaTeX).	257
			258	.. seealso::
	281		259
	282	Raw input cells	260	`Markdown Cells`_ example notebook
	283	~~~~~~~~~~~~~~~
	284		261
	285	Raw input cells provide a place in which you can write output directly.	262	Raw cells
	286	Raw cells are not evaluated by the Notebook, and have no output.	263	~~~~~~~~~
	287	When passed through nbconvert, Raw cells arrive in the destination format unmodified,	264
	288	allowing you to type full latex into a raw cell, which will only be rendered	265	Raw cells provide a place in which you can write output directly.
	289	by latex after conversion by nbconvert.	266	Raw cells are not evaluated by the notebook.
			267	When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
			268	destination format unmodified. For example, this allows you to type full LaTeX
			269	into a raw cell, which will only be rendered by LaTeX after conversion by
			270	nbconvert.
	290		271
	291	Heading cells	272	Heading cells
	292	~~~~~~~~~~~~~	273	~~~~~~~~~~~~~
	293		274
	294	You can provide a conceptual structure for your computational document as a	275	You can provide a conceptual structure for your computational document as a
	295	whole using different levels of headings; there are 6 levels available, from	276	whole using different levels of headings; there are 6 levels available, from
	296	level 1 (top level) down to level 6 (paragraph). These can be used later for	277	level 1 (top level) down to level 6 (paragraph). These can be used later for
	297	constructing tables of contents, etc.	278	constructing tables of contents, etc. As with Markdown cells, a heading
	298		279	cell is replaced by a rich text rendering of the heading when the cell is
	299	As with Markdown cells, a heading input cell is replaced by a rich text	280	executed.
	300	rendering of the heading when the cell is executed.
	301		281
	302		282
	303	Basic workflow	283	Basic workflow
	304	--------------	284	--------------
	305		285
	306	The normal workflow in a notebook is, then, quite similar to a standard	286	The normal workflow in a notebook is, then, quite similar to a standard
	307	IPython session, with the difference that you can edit cells in-place multiple	287	IPython session, with the difference that you can edit cells in-place multiple
	308	times until you obtain the desired results, rather than having to	288	times until you obtain the desired results, rather than having to
	309	rerun separate scripts with the ``%run`` magic command. ~~(Magic commands do,~~	289	rerun separate scripts with the ``%run`` magic command.
	310	however, also work in the notebook; see below).	290
	311		291
	312	Typically, you will work on a computational problem in pieces, organizing	292	Typically, you will work on a computational problem in pieces, organizing
	313	related ideas into cells and moving forward once previous parts work	293	related ideas into cells and moving forward once previous parts work
	314	correctly. This is much more convenient for interactive exploration than	294	correctly. This is much more convenient for interactive exploration than
	315	breaking up a computation into scripts that must be executed together, as was	295	breaking up a computation into scripts that must be executed together, as was
	316	previously necessary, especially if parts of them take a long time to run	296	previously necessary, especially if parts of them take a long time to run.
	317		297
	318	At certain moments, it may be necessary to interrupt a calculation which is	298	At certain moments, it may be necessary to interrupt a calculation which is
	319	taking too long to complete. This may be done with the ``Kernel \| Interrupt``	299	taking too long to complete. This may be done with the `Kernel \| Interrupt`
	320	menu option, or the :kbd:``Ctrl-i`` keyboard shortcut.	300	menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
	321	Similarly, it may be necessary or desirable to restart the whole computational	301	Similarly, it may be necessary or desirable to restart the whole computational
	322	process, with the ``Kernel \| Restart`` menu option or :kbd:``Ctrl-.``	302	process, with the `Kernel \| Restart` menu option or :kbd:`Ctrl-m .`
	323	shortcut. This gives an equivalent state to loading the notebook document	303	shortcut.
	324	afresh.
	325		304
	326	A notebook may be downloaded in either ``.ipynb`` or ~~raw~~ ``.py`` f~~orm~~ from the	305	A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
	327	menu option ``File \| Download as``. Choosing the ``.py`` option downloads a	306	menu option `File \| Download as`. Choosing the ``.py`` option downloads a
	328	Python ``.py`` script, in which all output has been removed and the ~~content of~~	307	Python ``.py`` script, in which all rich output has been removed and the
	329	Markdown cells in comment areas. See ref:`below <notebook_format>` for more	308	content of markdown cells have been inserted as comments.
	330	details on the notebook format.
	331		309
	332	.. warning::	310	.. seealso::
	333		311
	334	While in simple cases you can "roundtrip" a notebook to Python, edit the	312	`Running Code in the IPython Notebook`_ example notebook
	335	Python file, and then import it back without loss of main content, this is	313
	336	in general not guaranteed to work. First, there is extra metadata	314	`Basic Output`_ example notebook
	337	saved in the notebook that may not be saved to the ``.py`` format. And as
	338	the notebook format evolves in complexity, there will be attributes of the
	339	notebook that will not survive a roundtrip through the Python form. You
	340	should think of the Python format as a way to output a script version of a
	341	notebook and the import capabilities as a way to load existing code to get
	342	a notebook started. But the Python version is not an alternate notebook
	343	format.
	344		315
			316	:ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
			317
			318	.. _keyboard-shortcuts:
	345		319
	346	Keyboard shortcuts	320	Keyboard shortcuts
	347	~~~~~~~~~~~~~~~~~~	321	~~~~~~~~~~~~~~~~~~
	348	All actions in the notebook can be performed with the mouse, but keyboard	322	All actions in the notebook can be performed with the mouse, but keyboard
	349	shortcuts are also available for the most common ones. The essential shortcuts	323	shortcuts are also available for the most common ones. The essential shortcuts
	350	to remember are the following:	324	to remember are the following:
	351		325
	352	* :kbd:`Shift-Enter`: run cell	326	* :kbd:`Shift-Enter`: run cell
	353	Execute the current cell, show output (if any), and jump to the next cell	327	Execute the current cell, show output (if any), and jump to the next cell
	354	below. If :kbd:`Shift-Enter` is invoked on the last ~~input~~ cell, a new code	328	below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
	355	cell will also be created. Note that in the notebook, typing :kbd:`Enter`	329	cell will also be created. Note that in the notebook, typing :kbd:`Enter`
	356	on its own never forces execution, but rather just inserts a new line in	330	on its own never forces execution, but rather just inserts a new line in
	357	the current ~~input~~ cell. :kbd:`Shift-Enter` is equivalent to clicking the	331	the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
	358	``Cell \| Run`` menu item.	332	``Cell \| Run`` menu item.
	359		333
	360	* :kbd:`Ctrl-Enter`: run cell in-place	334	* :kbd:`Ctrl-Enter`: run cell in-place
	361	Execute the current cell as if it were in "terminal mode", where any	335	Execute the current cell as if it were in "terminal mode", where any
	362	output is shown, but the cursor remains in the current cell. The cell's	336	output is shown, but the cursor remains in the current cell. The cell's
	363	entire contents are selected after execution, so you can just start typing	337	entire contents are selected after execution, so you can just start typing
	364	and only the new input will be in the cell. This is convenient for doing	338	and only the new input will be in the cell. This is convenient for doing
	365	quick experiments in place, or for querying things like filesystem	339	quick experiments in place, or for querying things like filesystem
	366	content, without needing to create additional cells that you may not want	340	content, without needing to create additional cells that you may not want
	367	to be saved in the notebook.	341	to be saved in the notebook.
	368		342
	369	* :kbd:`Alt-Enter`: run cell, insert below	343	* :kbd:`Alt-Enter`: run cell, insert below
	370	Executes the current cell, shows the output, and inserts a new ~~input~~	344	Executes the current cell, shows the output, and inserts a new
	371	cell between the current cell and the cell below (if one exists). This	345	cell between the current cell and the cell below (if one exists). This
	372	is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.	346	is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
	373	(:kbd:`Ctrl-m a` adds a new cell above the current one.)	347	(:kbd:`Ctrl-m a` adds a new cell above the current one.)
	374		348
	375	* :kbd:`Ctrl-m`:	349	* :kbd:`Ctrl-m`:
	376	This is the prefix for all other shortcuts, which consist of :kbd:`Ctrl-m`	350	This is the prefix for all other shortcuts, which consist of :kbd:`Ctrl-m`
	377	followed by a single letter or character. For example, if you type	351	followed by a single letter or character. For example, if you type
	378	:kbd:`Ctrl-m h` (that is, the sole letter :kbd:`h` after :kbd:`Ctrl-m`),	352	:kbd:`Ctrl-m h` (that is, the sole letter :kbd:`h` after :kbd:`Ctrl-m`),
	379	IPython will show you all the available keyboard shortcuts.	353	IPython will show you all the available keyboard shortcuts.
	380		354
	381		355
	382	..	356	..
	383	TODO: these live in IPython/html/static/notebook/js/quickhelp.js	357	TODO: these live in IPython/html/static/notebook/js/quickhelp.js
	384	They were last updated for IPython 1.0 release, so update them again for	358	They were last updated for IPython 1.0 release, so update them again for
	385	future releases.	359	future releases.
	386		360
	387	Here is the complete set of keyboard shortcuts available:	361	Here is the complete set of keyboard shortcuts available:
	388		362
	389	============ ==========================	363	============ ==========================
	390	Shortcut Action	364	Shortcut Action
	391	------------ --------------------------	365	------------ --------------------------
	392	Shift-Enter run cell	366	Shift-Enter run cell
	393	Ctrl-Enter run cell in-place	367	Ctrl-Enter run cell in-place
	394	Alt-Enter run cell, insert below	368	Alt-Enter run cell, insert below
	395	Ctrl-m x cut cell	369	Ctrl-m x cut cell
	396	Ctrl-m c copy cell	370	Ctrl-m c copy cell
	397	Ctrl-m v paste cell	371	Ctrl-m v paste cell
	398	Ctrl-m d delete cell	372	Ctrl-m d delete cell
	399	Ctrl-m z undo last cell deletion	373	Ctrl-m z undo last cell deletion
	400	Ctrl-m - split cell	374	Ctrl-m - split cell
	401	Ctrl-m a insert cell above	375	Ctrl-m a insert cell above
	402	Ctrl-m b insert cell below	376	Ctrl-m b insert cell below
	403	Ctrl-m o toggle output	377	Ctrl-m o toggle output
	404	Ctrl-m O toggle output scroll	378	Ctrl-m O toggle output scroll
	405	Ctrl-m l toggle line numbers	379	Ctrl-m l toggle line numbers
	406	Ctrl-m s save notebook	380	Ctrl-m s save notebook
	407	Ctrl-m j move cell down	381	Ctrl-m j move cell down
	408	Ctrl-m k move cell up	382	Ctrl-m k move cell up
	409	Ctrl-m y code cell	383	Ctrl-m y code cell
	410	Ctrl-m m markdown cell	384	Ctrl-m m markdown cell
	411	Ctrl-m t raw cell	385	Ctrl-m t raw cell
	412	Ctrl-m 1-6 heading 1-6 cell	386	Ctrl-m 1-6 heading 1-6 cell
	413	Ctrl-m p select previous	387	Ctrl-m p select previous
	414	Ctrl-m n select next	388	Ctrl-m n select next
	415	Ctrl-m i interrupt kernel	389	Ctrl-m i interrupt kernel
	416	Ctrl-m . restart kernel	390	Ctrl-m . restart kernel
	417	Ctrl-m h show keyboard shortcuts	391	Ctrl-m h show keyboard shortcuts
	418	============ ==========================	392	============ ==========================
	419		393
	420		394
	421		395
	422	Magic commands
	423	--------------
	424	Magic commands, or magics, are commands for controlling IPython itself.
	425	They all begin with ``%`` and are entered into code input cells; the code
	426	cells are executed as usual with :kbd:`Shift-Enter`.
	427
	428	The magic commands call special functions defined by IPython which manipulate
	429	the computational state in certain ways.
	430
	431	There are two types of magics:
	432
	433	- line magics:
	434
	435	These begin with a single ``%`` and take as arguments the rest of the
	436	same line of the code cell. Any other lines of the code cell are
	437	treated as if they were part of a standard code cell.
	438
	439	- cell magics:
	440
	441	These begin with ``%%`` and operate on the entire remaining contents
	442	of the code cell.
	443
	444	Line magics
	445	~~~~~~~~~~~
	446	Some of the available line magics are the following:
	447
	448	* ``%load filename``:
	449
	450	Loads the contents of the file ``filename`` into a new code cell. This
	451	can be a URL for a remote file.
	452
	453	* ``%timeit code``:
	454
	455	An easy way to time how long the single line of code ``code`` takes to
	456	run
	457
	458	* ``%config``:
	459
	460	Configuration of the IPython Notebook
	461
	462	* ``%lsmagic``:
	463
	464	Provides a list of all available magic commands
	465
	466	Cell magics
	467	~~~~~~~~~~~
	468
	469	* ``%%latex``:
	470
	471	Renders the entire contents of the cell in LaTeX, without needing to use
	472	explicit LaTeX delimiters.
	473
	474	* ``%%bash``:
	475
	476	The code cell is executed by sending it to be executed by ``bash``. The
	477	output of the ``bash`` commands is captured and displayed in the
	478	notebook.
	479
	480	* ``%%file filename``:
	481
	482	Writes the contents of the cell to the file ``filename``.
	483	Caution: The file is over-written without warning!
	484
	485	* ``%%R``:
	486
	487	Execute the contents of the cell using the R language.
	488
	489	* ``%%timeit``:
	490
	491	Version of ``%timeit`` which times the entire block of code in the
	492	current code cell.
	493
	494
	495
	496	Several of the cell magics provide functionality to manipulate the filesystem
	497	of a remote server to which you otherwise do not have access.
	498		396
	499		397
	500	Plotting	398	Plotting
	501	--------	399	--------
	502	One major feature of the Notebook is the ability to ~~interact with~~	400	One major feature of the notebook is the ability to display plots that are the
	503	~~plots that are the~~ output of running code cells. IPython is designed to work	401	output of running code cells. IPython is designed to work seamlessly with the
	504	~~seamlessly with the~~ ``matplotlib`` plotting library to provide this	402	matplotlib_ plotting library to provide this functionality.
	505	functionality.
	506		403
	507	To set this up, before any plotting is performed you must execute the	404	To set this up, before any plotting is performed you must execute the
	508	``%matplotlib`` magic command. This performs the ~~necessary behind-the-scenes~~	405	``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
	509	setup for IPython to work correctly hand in hand ~~with~~ ~~``matplotlib``; it does~~	406	necessary behind-the-scenes setup for IPython to work correctly hand in hand
	510	not, however, actually execute any Python ``import`` commands, that is, no	407	with ``matplotlib``; it does not, however, actually execute any Python
	511	names are added to the namespace.	408	``import`` commands, that is, no names are added to the namespace.
	512		409
	513	If the ``%matplotlib`` magic is called without an argument, the	410	If the ``%matplotlib`` magic is called without an argument, the
	514	output of a plotting command is displayed using the default ``matplotlib``	411	output of a plotting command is displayed using the default ``matplotlib``
	515	backend in a separate window. Alternatively, the backend can be explicitly	412	backend in a separate window. Alternatively, the backend can be explicitly
	516	requested using, for example::	413	requested using, for example::
	517		414
	518	%matplotlib gtk	415	%matplotlib gtk
	519		416
	520	A particularly interesting backend is the ``inline`` ~~backend.~~	417	A particularly interesting backend, provided by IPython, is the ``inline``
	521	This is a~~pplic~~able only for the IPython Notebook and the ~~IPython QtConsole.~~	418	backend. This is available only for the IPython Notebook and the
	522	It can be invoked as follows::	419	:ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
	523		420
	524	%matplotlib inline	421	%matplotlib inline
	525		422
	526	With this backend, output of plotting commands is displayed inline ~~within~~	423	With this backend, the output of plotting commands is displayed inline
	527	the notebook ~~format~~, directly below the ~~input~~ cell that produced it. The	424	within the notebook, directly below the code cell that produced it. The
	528	resulting plots will then also be stored in the notebook document. ~~This~~	425	resulting plots will then also be stored in the notebook document.
	529	provides a key part of the functionality for reproducibility_ that the IPython
	530	Notebook provides.
	531		426
	532	.. _reproducibility: https://en.wikipedia.org/wiki/Reproducibility	427	.. seealso::
	533		428
			429	`Plotting with Matplotlib`_ example notebook
	534		430
	535		431
	536	Configuring the IPython Notebook	432	Configuring the IPython Notebook
	537	--------------------------------	433	--------------------------------
	538	The ~~IPytho~~n Notebook can be run with a variety of command line arguments.	434	The notebook server can be run with a variety of command line arguments.
	539	To see a list of available options enter::	435	To see a list of available options enter::
	540		436
	541	$ ipython notebook --help	437	$ ipython notebook --help
	542		438
	543	Defaults for these options can also be set by creating a file named	439	Defaults for these options can also be set by creating a file named
	544	``ipython_notebook_config.py`` in your IPython profile folder. The profile	440	``ipython_notebook_config.py`` in your IPython profile folder. The profile
	545	folder is a subfolder of your IPython directory; to find out where it is	441	folder is a subfolder of your IPython directory; to find out where it is
	546	located, run::	442	located, run::
	547		443
	548	$ ipython locate	444	$ ipython locate
	549		445
	550	To create a new set of default configuration files, with lots of information	446	To create a new set of default configuration files, with lots of information
	551	on available options, use::	447	on available options, use::
	552		448
	553	$ ipython profile create	449	$ ipython profile create
	554		450
	555	.. seealso::	451	.. seealso::
	556		452
	557	:ref:`config_overview`, in particular :ref:`Profiles`.	453	:ref:`config_overview`, in particular :ref:`Profiles`.
			454
			455	:ref:`notebook_security`
			456
			457	:ref:`notebook_public_server`
	558		458
	559		459
	560	Importing ``.py`` files	460	Importing ``.py`` files
	561	-----------------------	461	-----------------------
	562		462
	563	``.py`` files will be imported ~~into the IPython Notebook~~ as a notebook with	463	``.py`` files will be imported as a notebook with
	564	the same basename, but an ``.ipynb`` extension, located in the notebook	464	the same basename, but an ``.ipynb`` extension, located in the notebook
	565	directory. The notebook created will have just one cell, which will contain	465	directory. The notebook created will have just one cell, which will contain
	566	all the code in the ``.py`` file. You can later manually partition this into	466	all the code in the ``.py`` file. You can later manually partition this into
	567	individual cells using the ``Edit \| Split Cell`` menu option, or the	467	individual cells using the ``Edit \| Split Cell`` menu option, or the
	568	:kbd:`Ctrl-m -` keyboard shortcut.	468	:kbd:`Ctrl-m -` keyboard shortcut.
	569		469
	570	Note that ``.py`` scripts obtained from a notebook document using nbconvert_	470	Note that ``.py`` scripts obtained from a notebook document using nbconvert_
	571	maintain the structure of the notebook in comments. Reimporting such a	471	maintain the structure of the notebook in comments. Reimporting such a
	572	script back into ~~the N~~otebook will preserve this structxure.	472	script back into a notebook will preserve this structure.
	573		473
			474	.. _note_about_roundtrip:
	574		475
	575	.. warning::	476	.. warning::
	576		477
	577	You can "roundtrip" a notebook to Python, ~~by exporting~~ the	478	While in simple cases you can "roundtrip" a notebook to Python, edit the
	578	notebook to a ``.py`` script, editing the script, and then importing it back	479	Python file, and then import it back without loss of main content, this is
	579	into the Notebook without loss of main content. However,	480	in general not guaranteed to work. First, there is extra metadata
	580	in general this is not guaranteed to work. First, there is extra metadata	481	saved in the notebook that may not be saved to the ``.py`` format. And as
	581	saved in the notebook that may not be saved to the ``.py`` format. Second,	482	the notebook format evolves in complexity, there will be attributes of the
	582	as the notebook format evolves in complexity, there will be attributes of	483	notebook that will not survive a roundtrip through the Python form. You
	583	the notebook that will not survive a roundtrip through the Python form. You
	584	should think of the Python format as a way to output a script version of a	484	should think of the Python format as a way to output a script version of a
	585	notebook and the import capabilities as a way to load existing code to get	485	notebook and the import capabilities as a way to load existing code to get
	586	a notebook started. But the Python version is not an alternate notebook	486	a notebook started. But the Python version is not an alternate notebook
	587	format.	487	format.
	588		488
	589	.. seealso::	489	.. seealso::
	590	:ref:`notebook_format`	490	:ref:`notebook_format`
			491
			492	.. 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