aghz / ijavascript

IJavascript is a javascript kernel for IPython's graphical notebook

IJavascript: A Javascript Kernel for IPython's Graphical Notebook

IJavascript is an npm package that implements a Javasript kernel for IPython's graphical notebook (also known as Jupyter). An IPython notebook combines the creation of rich-text documents (including mathematics, plots and videos) with the execution of code in a number of programming languages.

The execution of code is carried out by means of a kernel that implements the IPython messaging protocol. There are kernels available for Python, Julia, Ruby, Haskell and many others.

IJavascript implements the latest stable specification of the protocol, version 4.1. This specification will be updated to version 5.0 in the next release of IPython.

A repository of IPython notebooks can be found here.

Prerequisites

The prerequisites vary from platform to platform.

Debian and Ubuntu

In recent Debian and Ubuntu distributions, it's enough to run the following command:

sudo apt-get install nodejs-legacy npm ipython ipython-notebook libzmq-dev

Ubuntu 12.04

In Ubuntu 12.04, both node.js and ipython need upgrading to a recent version:

sudo apt-get install libzmq-dev python-dev python-pip g++ curl
curl -sL https://deb.nodesource.com/setup | sudo bash -
sudo apt-get install -y nodejs
sudo pip install --upgrade ipython jinja2 tornado jsonschema pyzmq

The instructions for upgrading node.js have been adapted from those found here.

Other Platforms

For other platforms, instructions may be found at nodejs.org/download, ipython.org/install and zeromq.org/intro:get-the-software.

Installation

To install IJavascript globally (i.e. for all users in the system), run:

sudo npm install -g ijavascript

To install locally, run:

npm install ijavascript

In Debian and Ubuntu distributions, the above command will install the executable ijs in the folder ~/node_modules/.bin/. You may want to add this folder to your PATH:

echo \"PATH=\"\$HOME/node_modules/.bin\" >> ~/.profile

Note that the above change won't take effect until you log out of the current session.

Usage

To start an IPython notebook session with the Javascript kernel, simply run:

ijs

This command should open the IPython notebook dashboard in your default web browser:

By default, the dashboard opens the notebooks in the current working folder. The command flag --notebook-dir=path/to/another/folder can be used to open the dashboard at a different folder:

ijs --notebook-dir=path/to/another/folder

Here's a sample notebook that makes use of the Javascript kernel:

By default, the Javascript kernel doesn't define global. If security is not a concern global can be enabled by passing the following command flag:

ijs --ijs-enable-global

To obtain documentation for other command flags, run:

ipython notebook help

TO DO

• Capture stdout and stdin of each Javascript session (this may require replacing vm with vm2).

• Complete the implementation of IPython's messaging protocol.