Skip to content

Add Jupyter notebook support with OCaml kernel #20

@cuihtlauac

Description

@cuihtlauac

Summary

The devcontainer currently has no Jupyter support. Adding the ocaml-jupyter kernel would align well with the project's goal of zero-friction onboarding for tutorials and training sessions.

Prior art

KC Sivaramakrishnan used this stack to teach CS3100 (Paradigms of Programming) at IIT Madras:

Current state

Most prerequisites are already in the base image:

  • `python3` and `python3-pip`
  • System libraries needed by the OCaml kernel: `libgmp-dev`, `libffi-dev`, `zlib1g-dev`
  • `merlin` (used by the kernel for tab completion)

What's needed

1. System dependency (`base/Dockerfile`)

  • Add `libzmq5-dev` (ZeroMQ, for kernel-frontend communication)

2. OCaml kernel (`dev/Dockerfile`)

  • `opam install jupyter` — pulls in zmq, lwt, yojson, cryptokit, etc.
  • Run `ocaml-jupyter-opam-genspec` to generate the kernel spec
  • Run `jupyter kernelspec install` to register it
  • Register a kernel per switch so users can select between 5.4.0 and 5.4.0+tsan from the Jupyter notebook interface. Each switch needs its own kernelspec with a distinct display name (e.g., "OCaml 5.4.0", "OCaml 5.4.0+tsan").

3. Python-side Jupyter

  • `pip install jupyterlab`

4. nbgrader (optional, for autograding)

  • `pip install nbgrader` — Jupyter extension for creating, distributing, and auto-grading notebook assignments
  • Supports hidden test cells and read-only solution cells
  • Language-agnostic: works with OCaml cells out of the box
  • Known issue: KC reported nbgrader bugs where failing cells were incorrectly awarded grades. TAs should manually verify autograded results.
  • Reference: patricoferris/ocaml-teaching contains a working nbgrader example

5. RISE or equivalent (optional, for live presentations)

  • `pip install notebook rise` (for classic notebook) or `pip install jupyterlab-rise` (for JupyterLab)
  • Turns notebooks into live reveal.js slideshows — used by KC for lectures
  • Known limitation: KC reported poor font sizing and no diagramming support

6. DevContainer config

  • Forward port 8888 in `devcontainer.json`

7. Testing

  • Add `test/test-jupyter.sh` to verify kernel registration, server startup, and cell execution

Open questions

  • Install in both switches (5.4.0 and 5.4.0+tsan) or just the default? Lwt/zmq threading under TSan may produce false positives.
  • Estimated image size increase: ~100-170 MB (~3-5% of current size)
  • Estimated build time increase: ~5-10 min (zmq + lwt compilation)
  • Should nbgrader and RISE be in the main image or left for tutorial-specific layers?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions