Add more see also entries

docs/source/development/kernels.rst

@@ -1,145 +1,152
 ==========================
 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.
+     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/ipython/kernels``       | ``%PROGRAMDATA%\ipython\kernels`` |
 |        |                                      |                                   |
 |        | ``/usr/local/share/ipython/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 programming language which this kernel runs. This will be 
   stored in notebook metadata. This may be used by syntax highlighters to guess
   how to parse code in a notebook, and frontends may eventually use it to
   identify alternative kernels that can run some code.
 - **codemirror_mode** (optional): The `codemirror mode <http://codemirror.net/mode/index.html>`_
   to use for code in this language. This can be a string or a dictionary, as
   passed to codemirror config. The string from *language* will be used if this is
   not provided.
 - **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.
 - **help_links** (optional): A list of dictionaries, each with keys 'text' and
   'url'. These will be displayed in the help menu in the notebook UI.
 
 For example, the kernel.json file for IPython looks like this::
 
     {
      "argv": ["python3", "-c", "from IPython.kernel.zmq.kernelapp import main; main()", 
               "-f", "{connection_file}"], 
      "codemirror_mode": {
       "version": 3, 
       "name": "ipython"
      }, 
      "display_name": "IPython (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.

docs/source/development/wrapperkernels.rst

@@ -1,148 +1,153
 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
 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.
 
    .. 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`.
      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
         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
 
     class EchoKernel(Kernel):
         implementation = 'Echo'
         implementation_version = '1.0'
         language = 'no-op'
         language_version = '0.1'
         banner = "Echo kernel - as useful as a parrot"
 
         def do_execute(self, code, silent, store_history=True, user_experssions=None,
                        allow_stdin=False):
             if not silent:
                 stream_content = {'name': 'stdout', 'data':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
         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",
      "language":"no-op"
     }
 
 
 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_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