Documentation Site

[jeddeloh]

I'd really like to get a proper documentation site up. Some possibilities:

• Just hack together something with Docusaurus
• Use current OCamldoc to generate something: https://dev.to/yawaramin/publish-reasonml-api-docs-automatically-3c4i
• Wait for some new markdown enhancements to land in OCamldoc?

[jfrolich]

I am hacking on odoc (but not sure when I will arrive at anything good). Markdown support for doc comments /** ... */ will land in reason soon automatically converting it to ocamldoc so it will render in the documentation generator, so it would be good to document the bindings and modules using that even before we have good documentation generation and before markdown supports land.

[yawaramin]

@jfrolich Markdown support will land in Reason (I assume, at some point), but not in BuckleScript because BuckleScript is not upgrading its refmt version for the foreseeable future.

[jfrolich]

I hope we can land it in the new syntax as well. It is possible to use your own version of refmt with Bucklescript. Are you sure Bucklescript is not upgrading Reason? That would not be great. It wouldn't be so bad if they would decoupled and released separately though, but shipping an old version by default is not great I guess.

[yawaramin]

Based on what happened in rescript-lang/rescript-compiler#4271 and then after that the new syntax being publicized, I assume they won't upgrade. And I don't see Markdown docs landing in the new syntax in the near future either (in fact it will be a long road to get to even odoc support for the new syntax, i.e. parity with where Reason syntax is now).

If you want to publish API docs in the near future, your best bet is bsdoc with the current Reason syntax + ocamldoc markup.