docs: document experimental melange support

In particular, the new "melange" mode introduced for libraries.

Signed-off-by: Javier Chavarri <javier.chavarri@gmail.com>

doc/dune-files.rst

@@ -586,9 +586,10 @@ to use the :ref:`include_subdirs` stanza.
 
 - ``(modes <modes>)`` is for modes which should be built by default. The
   most common use for this feature is to disable native compilation
-  when writing libraries for the OCaml toplevel. The following modes
-  are available: ``byte``, ``native``, and ``best``. ``best`` is
-  ``native`` or ``byte`` when native compilation isn't available.
+  when writing libraries for the OCaml toplevel. It can also be used to define
+  libraries that should be compiled with Melange (see :ref:`melange_main`). The
+  following modes are available: ``byte``, ``native``, ``best``, and ``melange``.
+  ``best`` is ``native`` or ``byte`` when native compilation isn't available. 
 
 - ``(no_dynlink)`` disables dynamic linking of the library. This is for
   advanced use only. By default, you shouldn't set this option.

doc/index.rst

@@ -19,6 +19,7 @@ Welcome to Dune's Documentation!
    foreign-code
    documentation
    jsoo
+   melange
    sites
    opam
    variants

doc/jsoo.rst

@@ -1,8 +1,8 @@
 .. _jsoo:
 
-**********************
-JavaScript Compilation
-**********************
+***************************************
+JavaScript Compilation With Js_of_ocaml
+***************************************
 
 Js_of_ocaml_ is a compiler from OCaml to JavaScript. The compiler works by
 translating OCaml bytecode to JS files. The compiler can be installed with opam:

doc/melange.rst

@@ -0,0 +1,66 @@
+.. _melange_main:
+
+***********************************
+JavaScript Compilation With Melange
+***********************************
+
+`Melange <https://github.com/melange-re/melange>`_ is a compiler from OCaml to
+JavaScript. Unlike js_of_ocaml, Melange works by translating OCaml compiler
+internal lambda representation to JS files. This allows to produce a single
+JavaScript file from each OCaml module. Melange can be installed with
+`opam, Esy, or Nix <https://github.com/melange-re/melange#installation>`_ package
+managers.
+
+Compiling to JS
+===============
+
+Dune has experimental support for building Melange libraries. To use it, you
+must declare the ``melange`` extension in your ``dune-project`` file:
+
+.. code:: scheme
+
+  (lang dune 3.5)
+  (using melange 0.1)
+
+Then, given this example:
+
+.. code:: bash
+
+   echo 'Js.log "hello from melange"' > foo.ml
+
+With the following ``dune`` file:
+
+.. code:: scheme
+
+  (library (name foo) (modes melange))
+
+One can then request the ``.js`` target:
+
+.. code:: bash
+
+   $ dune build .foo.objs/melange/foo.js
+   $ node _build/default/.foo.objs/melange/foo.js
+   hello from melange
+
+At the moment, executable targets are not supported, but using explicit
+targets inside libraries as shown above should enable similar results.
+
+Faster Builds with ``subdir`` and ``dirs`` Stanzas
+==================================================
+
+Melange libraries are commonly installed from the ``npm`` package repository,
+together with other JavaScript packages. To avoid having Dune inspect
+unnecessary folders in ``node_modules``, it is recommended to explicitly
+include those folders that are relevant for Melange builds.
+
+This can be accomplished by combining :ref:`subdir` and :ref:`dune-subdirs`
+stanzas in a ``dune`` file and by co-locating this file together with the
+``node_modules`` folder. The :ref:`dune-vendored_dirs` stanza can be used as
+well to avoid warnings in Melange libraries during the application build.
+
+.. code:: scheme
+
+  (subdir
+   node_modules
+   (vendored_dirs reason-react)
+   (dirs reason-react))