From f9025a401a8789dc8a37adb89f0fd6c66018996c Mon Sep 17 00:00:00 2001
From: Rudi Grinberg <rudi.grinberg@gmail.com>
Date: Tue, 10 Oct 2017 16:35:47 -0400
Subject: [PATCH] Document utop command

---
 doc/usage.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/usage.rst b/doc/usage.rst
index 47097fc8..45f2397f 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -172,6 +172,31 @@ tests in a specific sub-directory and its children by using:
 -  ``jbuilder build @foo/bar/runtest``
 -  ``jbuilder runtest foo/bar``
 
+Launching the Toplevel (REPL)
+=============================
+
+jbuilder supports launching a `utop <https://github.com/diml/utop>`__ instance
+with locally defined libraries loaded.
+
+.. code:: bash
+
+   $ jbuilder utop <dir> -- <args>
+
+Where ``<dir>`` is a directory containing a ``jbuild`` file defining all the
+libraries that will be loaded (using the ``library`` stanza). ``<args>`` will be
+passed as arguments to the utop command itself. For example, to launch it in
+emacs mode.
+
+Requirements & Limitations
+--------------------------
+
+* utop version >= 2.0 is required for this to work.
+* This subcommand only supports loading libraries. Executables aren't supported.
+* Libraries that are dependencies of utop itself cannot be loaded. For example
+  `Camomile <https://github.com/yoriyuki/Camomile>`__.
+* Loading libraries that are defined in different directories into one utop
+  instance isn't possible.
+
 Restricting the set of packages
 ===============================