OCaml Jupyter

An OCaml kernel for Jupyter notebook.

This provides an OCaml REPL with a great user interface such as markdown/HTML documentation, LaTeX formula by MathJax, and image embedding.

Getting started

OCaml Jupyter requires the libraries zlib, libffi, libgmp, libzmq 5+. Type one of the following commands suitable for your environment.

# For Debian or Ubuntu:
sudo apt-get install -y zlib1g-dev libffi-dev libgmp-dev libzmq5-dev
# For REHL or CentOS:
sudo yum install -y epel-release
sudo yum install -y zlib-devel libffi-dev gmp-devel zeromq-devel
# For Mac OS X:
brew install zlib libffi gmp zeromq

OCaml Jupyter can be installed by OPAM as follows:

pip install jupyter
opam install jupyter
grep topfind ~/.ocamlinit || echo '#use "topfind";;' >> ~/.ocamlinit  # For using '#require' directive
grep Topfind.log ~/.ocamlinit || echo 'Topfind.log:=ignore;;' >> ~/.ocamlinit  # Suppress logging of topfind (recommended but not necessary)
ocaml-jupyter-opam-genspec
jupyter kernelspec install [ --user ] --name "ocaml-jupyter-$(opam var switch)" "$(opam var share)/jupyter"

If the last command fails due to permission, --user option or sudo is required. You can use ocaml-jupyter kernel by launching Jupyter notebook server:

jupyter notebook

Development version

opam pin add jupyter https://github.com/akabe/ocaml-jupyter.git

Usage

Examples

Introduction: a very simple example for use of OCaml Jupyter and sub-packages.
Get a description of a word from DuckDuckGo API: request to DuckDuckGo API server by cohttp.lwt, and parse a response JSON by yojson and ppx_yojson_conv.

In addition, many examples (e.g, image processing, voice analysis, etc.) are available at docker-ocaml-jupyter-datascience/notebooks.

These examples are placed in the public domain, e.g., you can edit, copy, and re-distribute with no copyright messages.

Code completion

OCaml Jupyter kernel supports merlin-based code completion. Candidates are shown by Tab key like

The kernel uses .merlin file at a notebook directory for completion.

Inspection

Inspection in Jupyter is also achieved by merlin. You can see documentation and type of an identifier by Shift+Tab key like

API documentation

OCaml Jupyter includes some sub-packages:

jupyter is a core library of OCaml Jupyter. This package is internally used. You don't need it directly.
jupyter.notebook is a library to control Jupyter from OCaml REPL in notebooks. This provides dynamic generation of HTML/markdown, and image embedding.
jupyter.comm is a library for communication between OCaml notebooks and Jupyter/Web frontend.

NBConvert

OCaml notebooks can be converted to HTML, Markdown, LaTeX, .ml files, etc. using the jupyter nbconvert command. For example, a .ipynb file is converted into a .html file as follows:

$ jupyter nbconvert --to html notebooks/introduction.ipynb
[NbConvertApp] Converting notebook notebooks/introduction.ipynb to html
[NbConvertApp] Writing 463004 bytes to notebooks/introduction.html

For exporting .ml files, we recommend Jupyter-NBConvert-OCaml. It outputs .ml files with Markdown cells as comments. After installation of Jupyter-NBConvert-OCaml, you can use --to ocaml option to export a .ml file:

$ jupyter nbconvert --to ocaml notebooks/introduction.ipynb
[NbConvertApp] Converting notebook notebooks/introduction.ipynb to ocaml
[NbConvertApp] Writing 2271 bytes to notebooks/introduction.ml

Customize kernel parameters

ocaml-jupyter-opam-genspec generates a configuration file like:

$ cat "$(opam var share)/jupyter/kernel.json"
{
  "display_name": "OCaml 4.08.1",
  "language": "OCaml",
  "argv": [
    "/bin/sh",
    "-c",
    "eval $(opam env --switch=4.08.1) && /home/xxxx/.opam/4.08.1/bin/ocaml-jupyter-kernel \"$@\"",
    "-init", "/home/xxxx/.ocamlinit",
    "--merlin", "/home/xxxx/.opam/4.08.1/bin/ocamlmerlin",
    "--verbosity", "app",
    "--connection-file", "{connection_file}"
  ]
}

See ocaml-jupyter-kernel --help for details of command-line parameters in argv. After you edit the file, re-register the kernel:

jupyter kernelspec install --name ocaml-jupyter "$(opam var share)/jupyter"

Installation without OPAM

ocaml-jupyter-opam-genspec depends on OPAM. If you use an other package manager, you need to write kernel.json by hand or use provided suitable way for registering a new kernel (e.g., jupyter module on Nix).

Running OCaml Jupyter on other environments

Binder

OCaml Jupyter can be run on Binder. Click the button to get started:

For more information, see this repository.

Google Colab

OCaml Jupyter can be run on Google Colab. In order to do this you first have to run this Python notebook in your Colab instance. This will install the kernel and after that OCaml notebooks can be used on the same instance.

Related work

Many Jupyter kernels for functional programming languages are available such as IHaskell, Jupyter Scala, and Jupyter Rust. IOCaml is another practical OCaml kernel that inspires us, but it seems no longer maintained. OCaml Jupyter kernel differs from IOCaml in

	OCaml Jupyter	IOCaml v0.4.8
Jupyter protocol	v5.2	v3.2
OCaml PPX support	Yes	No
Session key support	Yes	No
Code completion	Yes	Yes
Introspection	Yes	Yes
User-defined messages	Yes	No
Stdin	Yes	No

Another OCaml kernel simple_jucaml seems too simple to use in practice. jupyter-kernel is a library to write OCaml kernels (not a kernel), but OCaml Jupyter kernel does not use this library.

voodoos/ocaml-jupyter