search

jeddeloh / rescript-apollo-client

ReScript bindings for the Apollo Client ecosystem
MIT License
126 stars 18 forks source link

Documentation Site #20

Open jeddeloh opened 4 years ago

jeddeloh commented 4 years ago

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

jfrolich commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

Based on what happened in https://github.com/BuckleScript/bucklescript/pull/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.