Reason/OCaml syntax switching

[aantron]

This is about outputting docs in Reason syntax.

Nothing needs to be done at the parsing end, because odoc reads docs from parsed ASTs (after the OCaml or Reason parser is done running), so the source syntax doesn't affect odoc.

https://discuss.ocaml.org/t/1841/13, https://discuss.ocaml.org/t/1841/47. The Ocsigen website has an example of switching (http://ocsigen.org/lwt/3.2.1/api/Lwt). cc @Drup

[ryyppy]

Hey 👋
I am currently investing some time into this and try to submit a PR soon!

Hope this is okay?

[rizo]

The way I see this feature implemented and run is:

• Add the --syntax=ml|re option to odoc html.
• Implement an alternative HTML tree encoder for Reason.
• Generate both HTML trees.
• Have a button that changes the directory between ml and re trees.

@aantron What do you think about this approach?

[Drup]

Yeah, or you could just compile refmt to js and do the conversion of the fly.

[rizo]

@Drup I think it would be harder to achieve that for the signature items' markup. For examples, yes. But the markup is not purely textual, it has links and styling.

[aantron]

Hope this is okay?

It is, and quite welcome :)

@rizo, I think that works. My original thought was to generate both OCaml and Reason output side-by-side in each HTML file, and use CSS to hide/show the right one. But this is probably bad for accessibility, navigation, etc., so separate output trees are likely to be better.

[ryyppy]

My original thought was to generate both OCaml and Reason output side-by-side in each HTML file

I liked this idea as well... in my initial draft, I will just generate the whole documentation in ML / RE syntax side by side. Later on we can think of combining the output

[aantron]

@ryyppy added Reason syntax output in #156. Right now, odoc generates one of either ML or Reason syntax each time it is run. What's left on this topic is to decide whether we want to always generate both.

[ryyppy]

@aantron @Ostera @rizo So my idea to complete all of this was to basically generate both versions, but always hide one unselected version via CSS. By providing the --syntax flag, you will be able to decide on a default language to display whenever you load the docs for the first time.

As soon as this is done, we can add a JS-driven toggle for both syntaxes in the doc header.

[lpw25]

Not hard to do but can we make sure to have an option that only generates one or the other rather than both. Personally, I think that setting should be the default, but that's less important than having the option.