Generate docs for both reason & ocaml syntax

[feihong]

You can view the docs at https://ahrefs.github.io/melange-fest/ already

[feihong]

This will silence the deprecation warnings about old Node version

[feihong]

I set this so that the build directory is the same in CI even though no local switch is being used

[feihong]

I wish this could be a single command but I don't think it's possible

[jchavarri]

There might be a way to do this in a single command by leveraging Dune context, profiles and env vars.

In a new dune-workspace, add this:

(context (default (profile ml)))
(context (reason (profile re)))

; define env vars
(env
 (ml
  (env-vars
   (ODOC_SYNTAX ocaml))))
(env
 (re
  (env-vars
   (ODOC_SYNTAX reason))))

Then, a single run of dune build @doc should put the OCaml docs in _build/default/_doc/_html and the Reason ones in _build/reason/_doc/_html/.

[feihong]

I tried to get this to work, but ran into too many errors. Here's the last version I got before giving up:

(lang dune 3.8)

(context
 (default
  (profile ml)))

(context
 (reason
  (profile re)))

; define env vars

(env
 (ml
  (env-vars
   (ODOC_SYNTAX ocaml)))
 (re
  (env-vars
   (ODOC_SYNTAX reason))))

Running opam exec -- dune build @doc gave this error:

File "dune-workspace", line 8, characters 2-8:
8 |  (reason
      ^^^^^^
Error: Unknown constructor reason
make: *** [Makefile:59: docs] Error 1

[feihong]

It's possible to generate this page from mld file but I couldn't figure it out how to make it work well. The problem is that I always got some navigation elements at the top that I didn't want.

[feihong]

Actually, what's the reason for using alias_rec instead of just alias here?

[jchavarri]

The reason is the way Melange-Dune integration works and how aliases are attached to folder in Dune.

When dune finds a melange.emit stanza, it will create a lot of rules that generate all the artifacts needed for melange compilation (cmj, js and such). These rules are created into some inner folders in _build/default, and they get also "attached" to the alias of the melange.emit stanza (or the melange alias if undefined).

If we don't use alias_rec then some of these rules wouldn't execute and most probably the dependency wouldn't work properly. In other words alias_recis the way to tell Dune that the tests depend on any rule attached to this alias in the current folder, or any of its subfolders.

[feihong]

@jchavarri This JS code below, was it copied from somewhere? If so, maybe we should add a link to the source?

[jchavarri]

Yes! great point, I got it from here (I think): https://samthor.au/2022/test-react-builtin/

Feel free to add it to this PR or otherwise I can do it in a subsequent one.

[feihong]

Added link in cc56e26

[jchavarri]

Looks great, thanks so much for improving the readme ❤️

[jchavarri]

Yes! great point, I got it from here (I think): https://samthor.au/2022/test-react-builtin/

Feel free to add it to this PR or otherwise I can do it in a subsequent one.

[jchavarri]

The reason is the way Melange-Dune integration works and how aliases are attached to folder in Dune.

When dune finds a melange.emit stanza, it will create a lot of rules that generate all the artifacts needed for melange compilation (cmj, js and such). These rules are created into some inner folders in _build/default, and they get also "attached" to the alias of the melange.emit stanza (or the melange alias if undefined).

If we don't use alias_rec then some of these rules wouldn't execute and most probably the dependency wouldn't work properly. In other words alias_recis the way to tell Dune that the tests depend on any rule attached to this alias in the current folder, or any of its subfolders.