Add a way to display packages docs in Reason syntax

[jchavarri]

Thanks for all your work on maintaining and improving ocaml.org, it's amazing! ❤️

We are planning to link to the melange package page in ocaml.org from the project website, and one feature that we would be missing is showing the odoc generated signatures in Reason syntax.

I was chatting with @tmattio about the least intrusive way of adding a feature like this. Maybe it could be implemented as a query param ?syntax=re that can be optionally appended to the ocaml.org url, which would trigger the lazy loading of a script including the Reason parser bundled for the browser (refmt.js), which would dynamically target the DOM elements to translate them.

It would still not translate readmes like this: https://ocaml.org/p/printbox/latest/doc/PrintBox/index.html

But it would work on odoc pages like this: https://ocaml.org/p/printbox/latest/doc/PrintBox/Simple/index.html

[cuihtlauac]

If there was a server where translated to Reason syntax package documentation pages were available, the impact on ocaml.org would be minimal. When responding to ?syntax=re requests, we'd query that server instead of https://docs-data.ocaml.org/ where we get package pages content

[jchavarri]

the impact on ocaml.org would be minimal

is the concern the server time spent serving this refmt.js file? If that is the case, it could be aggresively cached in browsers or even I can prepare a package and publish in some cdn, so the impact in ocaml.org servers would be essentially zero. The server should just check for the syntax param and inject a <script/> element in the response.

If there was a server where translated to Reason syntax package documentation pages were available

This sounds like reimplementing what you all built for ocaml.org, which looks like... an incredible amount of work :) Do you have any pointers on how this server could leverage the infrastructure used in ocaml.org to minimize the costs of setting it up and maintain it?

[cuihtlauac]

the impact on ocaml.org would be minimal

I was referring to the implementation of ocaml.org. From project diff perspective, changing a hard-coded URL is the simplest. But you're correct, I wasn't looking at the complete picture.

What's the size of that refmt.js?

[jchavarri]

It is around 3MB (minimized, unzipped).

[cuihtlauac]

That's in the range of what we serve for the playground (used to be larger). We'll have more requests but we can't aim at total world dominance for ocaml without an increase of traffic:-)

[sabine]

I think serving refmt.js conditionally if the URL has a ?syntax=re querystring is fine. However, the navigation between pages would need to keep this querysting on the URLs, so that people don't always have to switch back to reason syntax. :thinking: