reason-react
reason-react copied to clipboard
Add initial docs for React module
Also add bsdoc as a devDep to allow generating docs locally and/or in CI/CD. Commands to generate docs:
npx bsdoc build React
npx bsdoc support-files # One-time setup but must be second step
open docs/React/React/index.html
Fix #559
@rickyvetter thanks for the review! To your question about how to integrate with Docusaurus sites, that may be a bit tricky. I'm not an expert on Docusaurus but when I researched it, it seemed to require all pages to be input in Markdown format. The documentation generated by bsdoc (really, odoc) is HTML format (with one CSS and one JS support file). If we can find a way to just serve the contents of the generated docs (it will be by default in a docs/
folder), that will work fine. Here's an example: https://reasonml-community.github.io/bs-webapi-incubator/api/Webapi/ (served by GitHub Pages from https://github.com/reasonml-community/bs-webapi-incubator/tree/gh-pages ).
Another thing I should mention: right now, odoc understands and can output OCaml and ReasonML syntaxes. If you want to generate docs in ReScript syntax, either the syntax support will need to be added to odoc (@ryyppy did this for Reason syntax), or some other workaround will be needed.
Can we split this up in two consecutive PRs that 1) add the missing inline docs and 2) add automatic docs generation?
Merging (1) would probably be a nobrainer. For 2) i believe there's still some work left to be able to render the docs in a meaningful way for ReScript developers, and I'd rather not expose them to the default odoc format tbh.
@ryyppy sure, I'll remove bsdoc from this PR. Nowadays I actually think it's better to do the doc generation part in a build step in CI and not have a dependency on bsdoc.
The odoc/ocamldoc format is the only way I know right now to get doc formatting, so not sure what that would be replaced with...