Add odoc syntax support

[ryyppy]

This is a tracking branch for #1117

Things which need to be done:

• Add syntax parameter to documentation stanza
• Use syntax parameter in the odoc call
• Add tests to test the right calling behavior

[emillon]

I think that "reason" & "ocaml" are enough. These names are also used in formatting rules for examples.

[emillon]

Other places use something like All | Only of syntax list which is more flexible - with this type you can not only enable a subset, it's all or only one. But this is not a problem since there are only two languages here.

[ryyppy]

I realized that All doesn't make sense anyways. odoc plans to provide both formats within the same html file, so the syntax option is only for the "preferred default syntax" later on

[ryyppy]

Currently I am having troubles with the fact that there might be multiple (documentation) stanzas, which could theoretically all have different configurations for the syntax flag.

After some discussion with @rgrinberg on Discord, one way to tackle this is to configure the odoc syntax flag via an env variable instead.

Generally speaking, after ocaml/odoc#129 is resolved, we might only need this flag for selecting a default syntax, but all RE / ML representations should be inlined in the docs and selectable in the UI anyways.

\cc @aantron

[ghost]

Generally speaking, after ocaml/odoc#129 is resolved, we might only need this flag for selecting a default syntax, but all RE / ML representations should be inlined in the docs and selectable in the UI anyways.

I'm wondering where is the best place to put this parameter. It seems more like a user preference to me, i.e. something that should live in ~/.config/odoc/....

[ryyppy]

@diml so my motivation behind this is following UX perspective: I am a Reason library designer and want to use odoc to generate my API, so my target group will most likely be Reason developers who want to see Reason-like syntax first.

If you don't provide any flag, it will default to OCaml. Generating the docs should IMO be reproducible, so I would not like to see user-based configuration mixed in.

There were some concerns that we should also offer a way to expose only one single syntax, so let's wait until ocaml/odoc#129 is resolved.

[emillon]

I agree that this should be reproductible, similarly to formatting rules not pulling global configuration.

[ghost]

I see, thanks for the explanation. In general, I assume that the developer will make this choice once for a given project, maybe it should go in the dune-project file then?

[trefis]

Also, one should note that there has been no release of odoc since v1.2 last year. That is: all the reason support is not on opam yet.
This should be kept in mind before merging things to dune.

[rgrinberg]

I see, thanks for the explanation. In general, I assume that the developer will make this choice once for a given project, maybe it should go in the dune-project file then?

Hmm, actually I agreed with your original point that it's probably more useful as a user preference for users of the package rather than the developers.

Also, one should note that there has been no release of odoc since v1.2 last year. That is: all the reason support is not on opam yet.

@aantron gave us a warning that there should be a new odoc release this week.

[ghost]

Indeed, btw I just remembered one question i had about this: if you are using a mix of OCaml and Reason libraries, do you expect to read the doc for OCaml libraries in OCaml syntax and the doc for Reason libraries in Reason syntax?

If yes, then there should indeed be a configuration parameter in dune about this. If not, i.e. you want to read everything in the same syntax, then it feels like a runtime configuration parameter is better suited. Dune doesn't need to know about the latter.

[rgrinberg]

Closing for staleness. Feel free to re-open once you are ready to make more progress.