Provide API docs

[nirvdrum]

I've just started out with React and ReasonML and read through all the docs on the ReasonReact website. However, I was unable to find any online documentation for the ReasonReact API. I've had to try to match up information from the ReactJS site or fall back to the ReasonReact source. While this works, it'd be really nice if the API documentation was available online, much like BuckleScript has.

[peterpme]

Hey @nirvdrum,

In an effort to clean up the repo (and given how old this issue is) I'm going to close this out for now.

Sorry about the delay. Please re-open if its still relevant.

Thanks!

[nirvdrum]

@peterpme To the best of my knowledge, the project hasn't published API docs anywhere. But, project collaborators would have more insight into that than me. Unfortunately, I don't have the permissions to re-open this issue even if the aforementioned docs are still unavailable.

[peterpme]

Re-opened! Would you be willing to help provide API docs by opening up a base PR?

[nirvdrum]

I could take a stab at it, but the reason I was looking for docs is because almost certainly someone else knows the API better than me. If I were to provide a stub for this, is there a preferred documentation tool?

[peterpme]

@nirvdrum that would be awesome! Create a file inside docs/api.md (copy a different doc like this one)

Then just open up a PR! I know for sure folks in the ReasonML Discord would help complete this :smile:

You'll have a great understanding of the API and contribute back to the core repo!

[mlms13]

It seems like API docs would be a good candidate for something like odoc, so they stay in sync with the actual code base. Maybe a good first step would be adding doc comments to the interface files in the format supported by odoc. Then we could wire up automatic generation each time a new version of reason-react is released.

[peterpme]

Hey @mlms13 that's an awesome idea! Do you want to help with that?

[mlms13]

Here's the Github Action script that we just started using: https://github.com/reazen/relude/blob/master/.github/workflows/release.yml

• Runs whenever a new tag is pushed (we did this instead of on every push to master because setting up the environment takes ~15 minutes... this could probably be improved)
• Sets up OCaml/odoc
• Installs esy and builds bsdoc from source for Linux
• Generates html pages in docs/api/ from odoc-formatted comments
• Publishes the whole docs/ folder on the gh-pages branch

There would be some repo-specific work to make sure it integrates with the existing (Docusaurus?) site, and obviously most of the doc comments would need to be written, but that should at least provide a starting point.

[nirvdrum]

Chewing this over more, I think it's pretty unlikely I'll be able to contribute the requested documentation here. I'm active in other open source projects and realistically won't be able to find the time to read through all of this project's code, internalize it, submit proposed API documentation in a tool I've never used before, and then go through the requisite back-and-forth of the draft review and edit process. It occurred to me earlier today that I haven't even written any ReasonML code in over two months because I've just been stymied by lots of beginner issues with various libraries (lack of documentation, dependency conflicts, waiting for bug fixes to be merged & released, etc.). I'd really like to contribute, but I don't want to give anyone any false hope. So, if you want to close this issue out, I completely understand.