reason-react icon indicating copy to clipboard operation
reason-react copied to clipboard

Add initial docs for React module

Open yawaramin opened this issue 4 years ago • 3 comments

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

yawaramin avatar Jun 28 '20 00:06 yawaramin

@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.

yawaramin avatar Aug 13 '20 23:08 yawaramin

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 avatar Sep 28 '20 07:09 ryyppy

@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...

yawaramin avatar Sep 28 '20 18:09 yawaramin