remove a few more docs that have been moved to other repos

docs/source/conf.py

@@ -1,266 +1,267 b''
 # -*- 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')
 
     # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
     for name in ('config', 'api', 'magics'):
         fname = 'autogen_{}.py'.format(name)
         fpath = os.path.abspath(os.path.join('..', fname))
         with open(fpath) as f:
             exec(compile(f.read(), fname, 'exec'), {
                 '__file__': fpath,
                 '__name__': '__main__',
             })
 
 # 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 = {}
 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),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.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
     'magics',
 ]
 
 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'] == 'dev':
     rst_prolog = """
     .. note::
 
         This documentation is for a development version of IPython. There may be
         significant differences from the latest stable release.
 
     """
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = 'The IPython Development Team'
 
 # ghissue config
 github_project_url = "https://github.com/ipython/ipython"
 
 # numpydoc config
 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
 numpydoc_class_members_toctree = False
 
 # 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.
 release = "%s" % iprelease['version']
 # 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 = []
 
 # Exclude these glob-style patterns when looking for source files. They are
 # relative to the source/ directory.
 exclude_patterns = ['whatsnew/pr']
 
 
 # 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'
 
 # Set the default role so we can use `foo` instead of ``foo``
 default_role = 'literal'
 
 # 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 = {
     'interactive/htmlnotebook': 'notebook_redirect.html',
     'interactive/notebook': 'notebook_redirect.html',
     'interactive/nbconvert': 'notebook_redirect.html',
     'interactive/public_server': 'notebook_redirect.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'
 
 intersphinx_mapping = {'python': ('http://docs.python.org/2/', None),
                        'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
                        'traitlets': ('http://traitlets.readthedocs.org/en/latest/', None),
                        'jupyterclient': ('http://jupyter-client.readthedocs.org/en/latest/', None),
+                       'ipyparallel': ('http://ipyparallel.readthedocs.org/en/latest/', None),
                       }
 
 # 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',
      u"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      u"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',
    1),
 ]
 
 modindex_common_prefix = ['IPython.']
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease

docs/source/development/how_ipython_works.rst

@@ -1,104 +1,63 b''
 How IPython works
 =================
 
 Terminal IPython
 ----------------
 
 When you type ``ipython``, you get the original IPython interface, running in
 the terminal. It does something like this::
 
     while True:
         code = input(">>> ")
         exec(code)
 
 Of course, it's much more complex, because it has to deal with multi-line
 code, tab completion using :mod:`readline`, magic commands, and so on. But the
 model is like that: prompt the user for some code, and when they've entered it,
 exec it in the same process. This model is often called a REPL, or
 Read-Eval-Print-Loop.
 
 The IPython Kernel
 ------------------
 
 All the other interfaces—the Notebook, the Qt console, ``ipython console`` in
 the terminal, and third party interfaces—use the IPython Kernel. This is a
 separate process which is responsible for running user code, and things like
 computing possible completions. Frontends communicate with it using JSON
 messages sent over `ZeroMQ <http://zeromq.org/>`_ sockets; the protocol they use is described in
-:doc:`messaging`.
+:ref:`jupyterclient:messaging`.
 
 The core execution machinery for the kernel is shared with terminal IPython:
 
 .. image:: figs/ipy_kernel_and_terminal.png
 
 A kernel process can be connected to more than one frontend simultaneously. In
 this case, the different frontends will have access to the same variables.
 
 .. TODO: Diagram illustrating this?
 
 This design was intended to allow easy development of different frontends based
 on the same kernel, but it also made it possible to support new languages in the
 same frontends, by developing kernels in those languages, and we are refining
 IPython to make that more practical.
 
 Today, there are two ways to develop a kernel for another language. Wrapper
 kernels reuse the communications machinery from IPython, and implement only the
 core execution part. Native kernels implement execution and communications in
 the target language:
 
 .. image:: figs/other_kernels.png
 
 Wrapper kernels are easier to write quickly for languages that have good Python
 wrappers, like `octave_kernel <https://pypi.python.org/pypi/octave_kernel>`_, or
 languages where it's impractical to implement the communications machinery, like
 `bash_kernel <https://pypi.python.org/pypi/bash_kernel>`_. Native kernels are
 likely to be better maintained by the community using them, like
 `IJulia <https://github.com/JuliaLang/IJulia.jl>`_ or `IHaskell <https://github.com/gibiansky/IHaskell>`_.
 
 .. seealso::
 
-   :doc:`kernels`
+   :ref:`jupyterclient:kernels`
    
    :doc:`wrapperkernels`
 
-Notebooks
----------
-
-The Notebook frontend does something extra. In addition to running your code, it
-stores code and output, together with markdown notes, in an editable document
-called a notebook. When you save it, this is sent from your browser to the
-notebook server, which saves it on disk as a JSON file with a ``.ipynb``
-extension.
-
-.. image:: figs/notebook_components.png
-
-The notebook server, not the kernel, is responsible for saving and loading
-notebooks, so you can edit notebooks even if you don't have the kernel for that
-language—you just won't be able to run code. The kernel doesn't know anything
-about the notebook document: it just gets sent cells of code to execute when the
-user runs them.
-
-Exporting to other formats
-``````````````````````````
-
-The Nbconvert tool in IPython converts notebook files to other formats, such as
-HTML, LaTeX, or reStructuredText. This conversion goes through a series of steps:
-
-.. image:: figs/nbconvert.png
-
-1. Preprocessors modify the notebook in memory. E.g. ExecutePreprocessor runs
-   the code in the notebook and updates the output.
-2. An exporter converts the notebook to another file format. Most of the
-   exporters use templates for this.
-3. Postprocessors work on the file produced by exporting.
-
-The `nbviewer <http://nbviewer.ipython.org/>`_ website uses nbconvert with the
-HTML exporter. When you give it a URL, it fetches the notebook from that URL,
-converts it to HTML, and serves that HTML to you.
-
-IPython.parallel
-----------------
-
-IPython also includes a parallel computing framework, ``IPython.parallel``. This
-allows you to control many individual engines, which are an extended version of
-the IPython kernel described above. For more details, see :doc:`/parallel/index`.

docs/source/development/index.rst

@@ -1,31 +1,28 b''
 .. _developer_guide:
 
 =========================
 IPython developer's guide
 =========================
 
 This are two categories of developer focused documentation:
 
 1. Documentation for developers of *IPython itself*.
 2. Documentation for developers of third party tools and libraries
    that use IPython.
 
 This part of our documentation only contains information in the second category.
 
 Developers interested in working on IPython itself should consult
 our `developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_ 
 on the IPython GitHub wiki.
 
 .. toctree::
    :maxdepth: 1
 
    how_ipython_works
-   kernels
    wrapperkernels
    execution
-   parallel_messages
-   parallel_connections
    lexer
    pycompat
    config
    inputhook_app

docs/source/development/kernels.rst

@@ -1,143 +1,8 b''
+:orphan:
+
 ==========================
 Making kernels for IPython
 ==========================
 
-A 'kernel' is a program that runs and introspects the user's code. IPython
-includes a kernel for Python code, and people have written kernels for
-`several other languages <https://github.com/ipython/ipython/wiki/Projects-using-IPython#list-of-some-ipython-compatible-kernels>`_.
-
-When IPython starts a kernel, it passes it a connection file. This specifies
-how to set up communications with the frontend.
-
-There are two options for writing a kernel:
-
-1. You can reuse the IPython kernel machinery to handle the communications, and
-   just describe how to execute your code. This is much simpler if the target
-   language can be driven from Python. See :doc:`wrapperkernels` for details.
-2. You can implement the kernel machinery in your target language. This is more
-   work initially, but the people using your kernel might be more likely to
-   contribute to it if it's in the language they know.
-
-Connection files
-================
-
-Your kernel will be given the path to a connection file when it starts (see
-:ref:`kernelspecs` for how to specify the command line arguments for your kernel).
-This file, which is accessible only to the current user, will contain a JSON
-dictionary looking something like this::
-
-    {
-      "control_port": 50160,
-      "shell_port": 57503,
-      "transport": "tcp",
-      "signature_scheme": "hmac-sha256",
-      "stdin_port": 52597,
-      "hb_port": 42540,
-      "ip": "127.0.0.1",
-      "iopub_port": 40885,
-      "key": "a0436f6c-1916-498b-8eb9-e81ab9368e84"
-    }
-
-The ``transport``, ``ip`` and five ``_port`` fields specify five ports which the
-kernel should bind to using `ZeroMQ <http://zeromq.org/>`_. For instance, the
-address of the shell socket in the example above would be::
-
-    tcp://127.0.0.1:57503
-
-New ports are chosen at random for each kernel started.
-
-``signature_scheme`` and ``key`` are used to cryptographically sign messages, so
-that other users on the system can't send code to run in this kernel. See
-:ref:`wire_protocol` for the details of how this signature is calculated.
-
-Handling messages
-=================
-
-After reading the connection file and binding to the necessary sockets, the
-kernel should go into an event loop, listening on the hb (heartbeat), control
-and shell sockets.
-
-:ref:`Heartbeat <kernel_heartbeat>` messages should be echoed back immediately
-on the same socket - the frontend uses this to check that the kernel is still
-alive.
-
-Messages on the control and shell sockets should be parsed, and their signature
-validated. See :ref:`wire_protocol` for how to do this.
-
-The kernel will send messages on the iopub socket to display output, and on the
-stdin socket to prompt the user for textual input.
-
-.. seealso::
-
-   :doc:`messaging`
-     Details of the different sockets and the messages that come over them
-
-   `Creating Language Kernels for IPython <http://andrew.gibiansky.com/blog/ipython/ipython-kernels/>`_
-     A blog post by the author of `IHaskell <https://github.com/gibiansky/IHaskell>`_,
-     a Haskell kernel
-
-   `simple_kernel <https://github.com/dsblank/simple_kernel>`_
-     A simple example implementation of the kernel machinery in Python
-
-
-.. _kernelspecs:
-
-Kernel specs
-============
-
-A kernel identifies itself to IPython by creating a directory, the name of which
-is used as an identifier for the kernel. These may be created in a number of
-locations:
-
-+--------+--------------------------------------+-----------------------------------+
-|        | Unix                                 | Windows                           |
-+========+======================================+===================================+
-| System | ``/usr/share/jupyter/kernels``       | ``%PROGRAMDATA%\jupyter\kernels`` |
-|        |                                      |                                   |
-|        | ``/usr/local/share/jupyter/kernels`` |                                   |
-+--------+--------------------------------------+-----------------------------------+
-| User   |                     ``~/.ipython/kernels``                               |
-+--------+--------------------------------------+-----------------------------------+
-
-The user location takes priority over the system locations, and the case of the
-names is ignored, so selecting kernels works the same way whether or not the
-filesystem is case sensitive.
-
-Inside the directory, the most important file is *kernel.json*. This should be a
-JSON serialised dictionary containing the following keys and values:
-
-- **argv**: A list of command line arguments used to start the kernel. The text
-  ``{connection_file}`` in any argument will be replaced with the path to the
-  connection file.
-- **display_name**: The kernel's name as it should be displayed in the UI.
-  Unlike the kernel name used in the API, this can contain arbitrary unicode
-  characters.
-- **language**: The name of the language of the kernel.
-  When loading notebooks, if no matching kernelspec key (may differ across machines)
-  is found, a kernel with a matching `language` will be used.
-  This allows a notebook written on any Python or Julia kernel to be properly associated
-  with the user's Python or Julia kernel, even if they aren't listed under the same name as the author's.
-- **env** (optional): A dictionary of environment variables to set for the kernel.
-  These will be added to the current environment variables before the kernel is
-  started.
-
-For example, the kernel.json file for IPython looks like this::
-
-    {
-     "argv": ["python3", "-m", "IPython.kernel",
-              "-f", "{connection_file}"],
-     "display_name": "Python 3",
-     "language": "python"
-    }
-
-To see the available kernel specs, run::
-
-    ipython kernelspec list
-
-To start the terminal console or the Qt console with a specific kernel::
-
-    ipython console --kernel bash
-    ipython qtconsole --kernel bash
-
-To use different kernels in the notebook, select a different kernel from the
-dropdown menu in the top-right of the UI.
+Kernels are now part of Jupyter - see
+:ref:`jupyterclient:kernels` for the documentation.

docs/source/development/parallel_connections.rst

@@ -1,154 +1,8 b''
-.. _parallel_connections:
+:orphan:
 
 ==============================================
 Connection Diagrams of The IPython ZMQ Cluster
 ==============================================
 
-This is a quick summary and illustration of the connections involved in the ZeroMQ based
-IPython cluster for parallel computing.
-
-All Connections
-===============
-
-The IPython cluster consists of a Controller, and one or more each of clients and engines.
-The goal of the Controller is to manage and monitor the connections and communications
-between the clients and the engines.  The Controller is no longer a single process entity,
-but rather a collection of processes - specifically one Hub, and 4 (or more) Schedulers.
-
-It is important for security/practicality reasons that all connections be inbound to the
-controller processes. The arrows in the figures indicate the direction of the
-connection.
-
-
-.. figure:: figs/allconnections.png
-    :width: 432px
-    :alt: IPython cluster connections
-    :align: center
-
-    All the connections involved in connecting one client to one engine.
-
-The Controller consists of 1-5 processes. Central to the cluster is the **Hub**, which monitors
-engine state, execution traffic, and handles registration and notification. The Hub includes a
-Heartbeat Monitor for keeping track of engines that are alive. Outside the Hub are 4
-**Schedulers**. These devices are very small pure-C MonitoredQueue processes (or optionally
-threads) that relay messages very fast, but also send a copy of each message along a side socket
-to the Hub. The MUX queue and Control queue are MonitoredQueue ØMQ devices which relay
-explicitly addressed messages from clients to engines, and their replies back up. The Balanced
-queue performs load-balancing destination-agnostic scheduling. It may be a MonitoredQueue
-device, but may also be a Python Scheduler that behaves externally in an identical fashion to MQ
-devices, but with additional internal logic. stdout/err are also propagated from the Engines to
-the clients via a PUB/SUB MonitoredQueue.
-
-
-Registration
-------------
-
-.. figure:: figs/queryfade.png
-    :width: 432px
-    :alt: IPython Registration connections
-    :align: center
-
-    Engines and Clients only need to know where the Query ``ROUTER`` is located to start
-    connecting. 
-
-Once a controller is launched, the only information needed for connecting clients and/or
-engines is the IP/port of the Hub's ``ROUTER`` socket called the Registrar. This socket
-handles connections from both clients and engines, and replies with the remaining
-information necessary to establish the remaining connections. Clients use this same socket for 
-querying the Hub for state information.
-
-Heartbeat
----------
-
-.. figure:: figs/hbfade.png
-    :width: 432px
-    :alt: IPython Heartbeat connections
-    :align: center
-
-    The heartbeat sockets.
-
-The heartbeat process has been described elsewhere. To summarize: the Heartbeat Monitor
-publishes a distinct message periodically via a ``PUB`` socket. Each engine has a
-``zmq.FORWARDER`` device with a ``SUB`` socket for input, and ``DEALER`` socket for output.
-The ``SUB`` socket is connected to the ``PUB`` socket labeled *ping*, and the ``DEALER`` is
-connected to the ``ROUTER`` labeled *pong*. This results in the same message being relayed
-back to the Heartbeat Monitor with the addition of the ``DEALER`` prefix. The Heartbeat
-Monitor receives all the replies via an ``ROUTER`` socket, and identifies which hearts are
-still beating by the ``zmq.IDENTITY`` prefix of the ``DEALER`` sockets, which information
-the Hub uses to notify clients of any changes in the available engines.
-
-Schedulers
-----------
-
-.. figure:: figs/queuefade.png
-    :width: 432px
-    :alt: IPython Queue connections
-    :align: center
-
-    Control message scheduler on the left, execution (apply) schedulers on the right.
-
-The controller has at least three Schedulers. These devices are primarily for
-relaying messages between clients and engines, but the Hub needs to see those
-messages for its own purposes. Since no Python code may exist between the two sockets in a
-queue, all messages sent through these queues (both directions) are also sent via a
-``PUB`` socket to a monitor, which allows the Hub to monitor queue traffic without
-interfering with it.
-
-For tasks, the engine need not be specified. Messages sent to the ``ROUTER`` socket from the
-client side are assigned to an engine via ZMQ's ``DEALER`` round-robin load balancing.
-Engine replies are directed to specific clients via the IDENTITY of the client, which is
-received as a prefix at the Engine.
-
-For Multiplexing, ``ROUTER`` is used for both in and output sockets in the device. Clients must
-specify the destination by the ``zmq.IDENTITY`` of the ``ROUTER`` socket connected to
-the downstream end of the device.
-
-At the Kernel level, both of these ``ROUTER`` sockets are treated in the same way as the ``REP``
-socket in the serial version (except using ZMQStreams instead of explicit sockets).
-
-Execution can be done in a load-balanced (engine-agnostic) or multiplexed (engine-specified)
-manner. The sockets on the Client and Engine are the same for these two actions, but the
-scheduler used determines the actual behavior. This routing is done via the ``zmq.IDENTITY`` of
-the upstream sockets in each MonitoredQueue.
-
-IOPub
------
-
-.. figure:: figs/iopubfade.png
-    :width: 432px
-    :alt: IOPub connections
-    :align: center
-
-    stdout/err are published via a ``PUB/SUB`` MonitoredQueue
-
-
-On the kernels, stdout/stderr are captured and published via a ``PUB`` socket. These ``PUB``
-sockets all connect to a ``SUB`` socket input of a MonitoredQueue, which subscribes to all
-messages. They are then republished via another ``PUB`` socket, which can be
-subscribed by the clients.
-
-Client connections
-------------------
-
-.. figure:: figs/queryfade.png
-    :width: 432px
-    :alt: IPython client query connections
-    :align: center
-
-    Clients connect to an ``ROUTER`` socket to query the hub.
-
-The hub's registrar ``ROUTER`` socket also listens for queries from clients as to queue status,
-and control instructions. Clients connect to this socket via an ``DEALER`` during registration.
-
-.. figure:: figs/notiffade.png
-    :width: 432px
-    :alt: IPython Registration connections
-    :align: center
-
-    Engine registration events are published via a ``PUB`` socket.
-
-The Hub publishes all registration/unregistration events via a ``PUB`` socket. This
-allows clients to stay up to date with what engines are available by subscribing to the
-feed with a ``SUB`` socket. Other processes could selectively subscribe to just
-registration or unregistration events.
-
+IPython parallel has moved to ipyparallel -
+see :ref:`ipyparallel:parallel_connections` for the documentation.

docs/source/development/parallel_messages.rst

@@ -1,367 +1,8 b''
-.. _parallel_messages:
+:orphan:
 
+================================
 Messaging for Parallel Computing
 ================================
 
-This is an extension of the :ref:`messaging <messaging>` doc. Diagrams of the connections
-can be found in the :ref:`parallel connections <parallel_connections>` doc.
-
-
-ZMQ messaging is also used in the parallel computing IPython system. All messages to/from
-kernels remain the same as the single kernel model, and are forwarded through a ZMQ Queue
-device. The controller receives all messages and replies in these channels, and saves
-results for future use.
-
-The Controller
---------------
-
-The controller is the central collection of processes in the IPython parallel computing
-model. It has two major components:
-
-    * The Hub
-    * A collection of Schedulers
-
-The Hub
--------
-
-The Hub is the central process for monitoring the state of the engines, and all task
-requests and results.  It has no role in execution and does no relay of messages, so
-large blocking requests or database actions in the Hub do not have the ability to impede
-job submission and results.
-
-Registration (``ROUTER``)
-*************************
-
-The first function of the Hub is to facilitate and monitor connections of clients
-and engines. Both client and engine registration are handled by the same socket, so only
-one ip/port pair is needed to connect any number of connections and clients.
-
-Engines register with the ``zmq.IDENTITY`` of their two ``DEALER`` sockets, one for the
-queue, which receives execute requests, and one for the heartbeat, which is used to
-monitor the survival of the Engine process.
-
-Message type: ``registration_request``::
-
-    content = {
-        'uuid'   : 'abcd-1234-...', # the zmq.IDENTITY of the engine's sockets
-    }
-
-.. note::
-
-    these are always the same, at least for now.
-
-The Controller replies to an Engine's registration request with the engine's integer ID,
-and all the remaining connection information for connecting the heartbeat process, and
-kernel queue socket(s). The message status will be an error if the Engine requests IDs that
-already in use.
-
-Message type: ``registration_reply``::
-
-    content = {
-        'status' : 'ok', # or 'error'
-        # if ok:
-        'id' : 0, # int, the engine id
-    }
-
-Clients use the same socket as engines to start their connections. Connection requests
-from clients need no information:
-
-Message type: ``connection_request``::
-    
-    content = {}
-
-The reply to a Client registration request contains the connection information for the
-multiplexer and load balanced queues, as well as the address for direct hub
-queries. If any of these addresses is `None`, that functionality is not available.
-
-Message type: ``connection_reply``::
-
-    content = {
-        'status' : 'ok', # or 'error'
-    }
-
-Heartbeat
-*********
-
-The hub uses a heartbeat system to monitor engines, and track when they become
-unresponsive. As described in :ref:`messaging <messaging>`, and shown in :ref:`connections
-<parallel_connections>`.
-
-Notification (``PUB``)
-**********************
-
-The hub publishes all engine registration/unregistration events on a ``PUB`` socket.
-This allows clients to have up-to-date engine ID sets without polling. Registration
-notifications contain both the integer engine ID and the queue ID, which is necessary for
-sending messages via the Multiplexer Queue and Control Queues.
-
-Message type: ``registration_notification``::
-
-    content = {
-        'id' : 0, # engine ID that has been registered
-        'uuid' : 'engine_id' # the IDENT for the engine's sockets
-    }
-
-Message type : ``unregistration_notification``::
-
-    content = {
-        'id' : 0 # engine ID that has been unregistered
-        'uuid' : 'engine_id' # the IDENT for the engine's sockets
-    }
-
-
-Client Queries (``ROUTER``)
-***************************
-
-The hub monitors and logs all queue traffic, so that clients can retrieve past
-results or monitor pending tasks. This information may reside in-memory on the Hub, or
-on disk in a database (SQLite and MongoDB are currently supported).  These requests are
-handled by the same socket as registration.
-
-
-:func:`queue_request` requests can specify multiple engines to query via the `targets`
-element. A verbose flag can be passed, to determine whether the result should be the list
-of `msg_ids` in the queue or simply the length of each list.
-
-Message type: ``queue_request``::
-
-    content = {
-        'verbose' : True, # whether return should be lists themselves or just lens
-        'targets' : [0,3,1] # list of ints
-    }
-
-The content of a reply to a :func:`queue_request` request is a dict, keyed by the engine
-IDs. Note that they will be the string representation of the integer keys, since JSON
-cannot handle number keys.  The three keys of each dict are::
-
-    'completed' :  messages submitted via any queue that ran on the engine
-    'queue' : jobs submitted via MUX queue, whose results have not been received
-    'tasks' : tasks that are known to have been submitted to the engine, but 
-                have not completed.  Note that with the pure zmq scheduler, this will
-                always be 0/[].
-
-Message type: ``queue_reply``::
-
-    content = {
-        'status' : 'ok', # or 'error'
-        # if verbose=False:
-        '0' : {'completed' : 1, 'queue' : 7, 'tasks' : 0},
-        # if verbose=True:
-        '1' : {'completed' : ['abcd-...','1234-...'], 'queue' : ['58008-'], 'tasks' : []},
-    }
-
-Clients can request individual results directly from the hub. This is primarily for
-gathering results of executions not submitted by the requesting client, as the client
-will have all its own results already. Requests are made by msg_id, and can contain one or
-more msg_id. An additional boolean key 'statusonly' can be used to not request the
-results, but simply poll the status of the jobs.
-
-Message type: ``result_request``::
-
-    content = {
-        'msg_ids' : ['uuid','...'], # list of strs
-        'targets' : [1,2,3], # list of int ids or uuids
-        'statusonly' : False, # bool
-    }
-
-The :func:`result_request` reply contains the content objects of the actual execution
-reply messages. If `statusonly=True`, then there will be only the 'pending' and
-'completed' lists.  
-
-
-Message type: ``result_reply``::
-
-    content = {
-        'status' : 'ok', # else error
-        # if ok:
-        'acbd-...' : msg, # the content dict is keyed by msg_ids,
-                         # values are the result messages
-                        # there will be none of these if `statusonly=True`
-        'pending' : ['msg_id','...'], # msg_ids still pending
-        'completed' : ['msg_id','...'], # list of completed msg_ids
-    }
-    buffers = ['bufs','...'] # the buffers that contained the results of the objects.
-                            # this will be empty if no messages are complete, or if 
-                            # statusonly is True.
-
-For memory management purposes, Clients can also instruct the hub to forget the
-results of messages. This can be done by message ID or engine ID. Individual messages are
-dropped by msg_id, and all messages completed on an engine are dropped by engine ID. This
-may no longer be necessary with the mongodb-based message logging backend.
-
-If the msg_ids element is the string ``'all'`` instead of a list, then all completed
-results are forgotten.
-
-Message type: ``purge_request``::
-
-    content = {
-        'msg_ids' : ['id1', 'id2',...], # list of msg_ids or 'all'
-        'engine_ids' : [0,2,4] # list of engine IDs
-    }
-
-The reply to a purge request is simply the status 'ok' if the request succeeded, or an
-explanation of why it failed, such as requesting the purge of a nonexistent or pending
-message.
-
-Message type: ``purge_reply``::
-
-    content = {
-        'status' : 'ok', # or 'error'
-    }
-
-
-Schedulers
-----------
-
-There are three basic schedulers:
-
-  * Task Scheduler
-  * MUX Scheduler
-  * Control Scheduler
-
-The MUX and Control schedulers are simple MonitoredQueue ØMQ devices, with ``ROUTER``
-sockets on either side. This allows the queue to relay individual messages to particular
-targets via ``zmq.IDENTITY`` routing. The Task scheduler may be a MonitoredQueue ØMQ
-device, in which case the client-facing socket is ``ROUTER``, and the engine-facing socket
-is ``DEALER``.  The result of this is that client-submitted messages are load-balanced via 
-the ``DEALER`` socket, but the engine's replies to each message go to the requesting client.
-
-Raw ``DEALER`` scheduling is quite primitive, and doesn't allow message introspection, so
-there are also Python Schedulers that can be used. These Schedulers behave in much the
-same way as a MonitoredQueue does from the outside, but have rich internal logic to
-determine destinations, as well as handle dependency graphs Their sockets are always
-``ROUTER`` on both sides.
-
-The Python task schedulers have an additional message type, which informs the Hub of
-the destination of a task as soon as that destination is known.
-
-Message type: ``task_destination``::
-
-    content = {
-        'msg_id' : 'abcd-1234-...', # the msg's uuid
-        'engine_id' : '1234-abcd-...', # the destination engine's zmq.IDENTITY
-    }
-
-:func:`apply`
-*************
-
-In terms of message classes, the MUX scheduler and Task scheduler relay the exact same
-message types.  Their only difference lies in how the destination is selected.
-
-The `Namespace <http://gist.github.com/483294>`_ model suggests that execution be able to
-use the model::
-
-    ns.apply(f, *args, **kwargs)
-    
-which takes `f`, a function in the user's namespace, and executes ``f(*args, **kwargs)``
-on a remote engine, returning the result (or, for non-blocking, information facilitating
-later retrieval of the result). This model, unlike the execute message which just uses a
-code string, must be able to send arbitrary (pickleable) Python objects. And ideally, copy
-as little data as we can. The `buffers` property of a Message was introduced for this
-purpose.
-
-Utility method :func:`build_apply_message` in :mod:`IPython.kernel.zmq.serialize` wraps a
-function signature and builds a sendable buffer format for minimal data copying (exactly
-zero copies of numpy array data or buffers or large strings).
-
-Message type: ``apply_request``::
-
-    metadata = {
-        'after' : ['msg_id',...], # list of msg_ids or output of Dependency.as_dict()
-        'follow' : ['msg_id',...], # list of msg_ids or output of Dependency.as_dict()
-    }
-    content = {}
-    buffers = ['...'] # at least 3 in length
-                    # as built by build_apply_message(f,args,kwargs)
-
-after/follow represent task dependencies. 'after' corresponds to a time dependency. The
-request will not arrive at an engine until the 'after' dependency tasks have completed.
-'follow' corresponds to a location dependency. The task will be submitted to the same
-engine as these msg_ids (see :class:`Dependency` docs for details).
-
-Message type: ``apply_reply``::
-
-    content = {
-        'status' : 'ok' # 'ok' or 'error'
-        # other error info here, as in other messages
-    }
-    buffers = ['...'] # either 1 or 2 in length
-                    # a serialization of the return value of f(*args,**kwargs)
-                    # only populated if status is 'ok'
-
-All engine execution and data movement is performed via apply messages.
-
-Control Messages
-----------------
-
-Messages that interact with the engines, but are not meant to execute code, are submitted
-via the Control queue. These messages have high priority, and are thus received and
-handled before any execution requests.
-
-Clients may want to clear the namespace on the engine. There are no arguments nor
-information involved in this request, so the content is empty.
-
-Message type: ``clear_request``::
-
-    content = {}
-
-Message type: ``clear_reply``::
-
-    content = {
-        'status' : 'ok' # 'ok' or 'error'
-        # other error info here, as in other messages
-    }
-
-Clients may want to abort tasks that have not yet run. This can by done by message id, or
-all enqueued messages can be aborted if None is specified.
-
-Message type: ``abort_request``::
-
-    content = {
-        'msg_ids' : ['1234-...', '...'] # list of msg_ids or None
-    }
-
-Message type: ``abort_reply``::
-
-    content = {
-        'status' : 'ok' # 'ok' or 'error'
-        # other error info here, as in other messages
-    }
-
-The last action a client may want to do is shutdown the kernel. If a kernel receives a
-shutdown request, then it aborts all queued messages, replies to the request, and exits.
-
-Message type: ``shutdown_request``::
-
-    content = {}
-
-Message type: ``shutdown_reply``::
-
-    content = {
-        'status' : 'ok' # 'ok' or 'error'
-        # other error info here, as in other messages
-    }
-
-
-Implementation
---------------
-
-There are a few differences in implementation between the `StreamSession` object used in
-the newparallel branch and the `Session` object, the main one being that messages are
-sent in parts, rather than as a single serialized object. `StreamSession` objects also
-take pack/unpack functions, which are to be used when serializing/deserializing objects.
-These can be any functions that translate to/from formats that ZMQ sockets can send
-(buffers,bytes, etc.).
-
-Split Sends
-***********
-
-Previously, messages were bundled as a single json object and one call to
-:func:`socket.send_json`. Since the hub inspects all messages, and doesn't need to
-see the content of the messages, which can be large, messages are now serialized and sent in
-pieces. All messages are sent in at least 4 parts: the header, the parent header, the metadata and the content.
-This allows the controller to unpack and inspect the (always small) header,
-without spending time unpacking the content unless the message is bound for the
-controller. Buffers are added on to the end of the message, and can be any objects that
-present the buffer interface.
-
+IPython parallel has moved to ipyparallel -
+see :ref:`ipyparallel:parallel_messages` for the documentation.

docs/source/development/wrapperkernels.rst

@@ -1,175 +1,175 b''
 Making simple Python wrapper kernels
 ====================================
 
 .. versionadded:: 3.0
 
 You can now re-use the kernel machinery in IPython to easily make new kernels.
 This is useful for languages that have Python bindings, such as `Octave
 <http://www.gnu.org/software/octave/>`_ (via
 `Oct2Py <http://blink1073.github.io/oct2py/docs/index.html>`_), or languages
 where the REPL can be controlled in a tty using `pexpect <http://pexpect.readthedocs.org/en/latest/>`_,
 such as bash.
 
 .. seealso::
 
    `bash_kernel <https://github.com/takluyver/bash_kernel>`_
      A simple kernel for bash, written using this machinery
 
 Required steps
 --------------
 
-Subclass :class:`IPython.kernel.zmq.kernelbase.Kernel`, and implement the
+Subclass :class:`ipykernel.kernelbase.Kernel`, and implement the
 following methods and attributes:
 
 .. class:: MyKernel
 
    .. attribute:: implementation
                   implementation_version
                   language
                   language_version
                   banner
     
      Information for :ref:`msging_kernel_info` replies. 'Implementation' refers
      to the kernel (e.g. IPython), and 'language' refers to the language it
      interprets (e.g. Python). The 'banner' is displayed to the user in console
      UIs before the first prompt. All of these values are strings.
 
    .. attribute:: language_info
 
      Language information for :ref:`msging_kernel_info` replies, in a dictionary.
      This should contain the key ``mimetype`` with the mimetype of code in the
      target language (e.g. ``'text/x-python'``), and ``file_extension`` (e.g.
      ``'py'``).
      It may also contain keys ``codemirror_mode`` and ``pygments_lexer`` if they
      need to differ from :attr:`language`.
 
      Other keys may be added to this later.
 
    .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
    
      Execute user code.
      
      :param str code: The code to be executed.
      :param bool silent: Whether to display output.
      :param bool store_history: Whether to record this code in history and
          increase the execution count. If silent is True, this is implicitly
          False.
      :param dict user_expressions: Mapping of names to expressions to evaluate
          after the code has run. You can ignore this if you need to.
      :param bool allow_stdin: Whether the frontend can provide input on request
          (e.g. for Python's :func:`raw_input`).
      
      Your method should return a dict containing the fields described in
      :ref:`execution_results`. To display output, it can send messages
-     using :meth:`~IPython.kernel.zmq.kernelbase.Kernel.send_response`.
+     using :meth:`~ipykernel.kernelbase.Kernel.send_response`.
      See :doc:`messaging` for details of the different message types.
 
 To launch your kernel, add this at the end of your module::
 
     if __name__ == '__main__':
-        from IPython.kernel.zmq.kernelapp import IPKernelApp
+        from ipykernel.kernelapp import IPKernelApp
         IPKernelApp.launch_instance(kernel_class=MyKernel)
 
 Example
 -------
 
 ``echokernel.py`` will simply echo any input it's given to stdout::
 
-    from IPython.kernel.zmq.kernelbase import Kernel
+    from ipykernel.kernelbase import Kernel
 
     class EchoKernel(Kernel):
         implementation = 'Echo'
         implementation_version = '1.0'
         language = 'no-op'
         language_version = '0.1'
         language_info = {'mimetype': 'text/plain'}
         banner = "Echo kernel - as useful as a parrot"
 
         def do_execute(self, code, silent, store_history=True, user_expressions=None,
                        allow_stdin=False):
             if not silent:
                 stream_content = {'name': 'stdout', 'text': code}
                 self.send_response(self.iopub_socket, 'stream', stream_content)
 
             return {'status': 'ok',
                     # The base class increments the execution count
                     'execution_count': self.execution_count,
                     'payload': [],
                     'user_expressions': {},
                    }
 
     if __name__ == '__main__':
-        from IPython.kernel.zmq.kernelapp import IPKernelApp
+        from ipykernel.kernelapp import IPKernelApp
         IPKernelApp.launch_instance(kernel_class=EchoKernel)
 
 Here's the Kernel spec ``kernel.json`` file for this::
 
     {"argv":["python","-m","echokernel", "-f", "{connection_file}"],
      "display_name":"Echo"
     }
 
 
 Optional steps
 --------------
 
 You can override a number of other methods to improve the functionality of your
 kernel. All of these methods should return a dictionary as described in the
 relevant section of the :doc:`messaging spec <messaging>`.
 
 .. class:: MyKernel
 
    .. method:: do_complete(code, cusor_pos)
 
      Code completion
      
      :param str code: The code already present
      :param int cursor_pos: The position in the code where completion is requested
      
      .. seealso::
      
         :ref:`msging_completion` messages
 
    .. method:: do_inspect(code, cusor_pos, detail_level=0)
 
      Object introspection
      
      :param str code: The code
      :param int cursor_pos: The position in the code where introspection is requested
      :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets
          the source code.
      
      .. seealso::
      
         :ref:`msging_inspection` messages
 
    .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)
 
      History access. Only the relevant parameters for the type of history
      request concerned will be passed, so your method definition must have defaults
      for all the arguments shown with defaults here.
 
      .. seealso::
      
         :ref:`msging_history` messages
 
    .. method:: do_is_complete(code)
    
      Is code entered in a console-like interface complete and ready to execute,
      or should a continuation prompt be shown?
      
      :param str code: The code entered so far - possibly multiple lines
      
      .. seealso::
      
         :ref:`msging_is_complete` messages
 
    .. method:: do_shutdown(restart)
 
      Shutdown the kernel. You only need to handle your own clean up - the kernel
      machinery will take care of cleaning up its own things before stopping.
      
      :param bool restart: Whether the kernel will be started again afterwards
      
      .. seealso::
      
         :ref:`msging_shutdown` messages