State of rescript lib Docs

1

Hello everyone,

I’m keen to know, how the rescript library authors of you approach documentation for such a lib?

  • Do you just write a (simple?) readme?
  • Do you have api docs? (How? Where?)
  • Do you use doc-comments in rescript files?
  • Do you generate some part of your docs? ( which part? How?)
  • Do you write (all?) docs by hand?
  • Do you use a site-generator? (Which one?)
  • What’s your general approach and thoughts?

The release of rescript-tools marks the date of official doc-gen tooling support.
I started tinkering with doc-gen some time ago and I’d like to know your thoughts, ideas and current pain-points. It would be great to find a consensus what’s the most needed tooling related to docs.

5 Likes
2

Ideally, it all should be generated from code and hosted somewhere, like it’s done in Rust.

When I need docs for any of a Rust library, I don’t waste time on rambling. I go straight to docs.rs right from my editor. It’s all there, with unified interface, guaranteed correct.

1 Like
3

The rust approach requires additional infrastructure. We don’t have a package manager.

My suggestion is to use Package Index | ReScript Documentation as an indexer.

  • The user adds keywords and we search the npm registry for the keyword rescript package.json | npm Docs
  • Add homepage property to the URL of the website where you hosted it.

We search on npm registry and add a button See docs.

What do you think?

4

Thanks for doing this woeps, its coming to me at just a perfect time.

1 Like
5

It would be fantastic if we could gather up a little group of interested people and drive this over the finish line. We have a lot of the needed parts, now just need to tweak them and put them together.

@woeps thanks for your engagement so far, please feel free to ping me for whatever you need and I’m sure we can figure out how to move docgen stuff forward in a good way.

2 Likes
6

Here’s my tool for producing markdown from the json:

I notice that tools is for rescript 11+?
We are still on 10, and going to be there a while until graphql sorts out, so wrote my own types and parser. A little fragile but working in our code so far…

A

3 Likes
7

speaking of types? i notice that modules are simple items and do not contain their children? That might be nice to do in tools? [edit, no it looks like they are nested. sorry!]

1 Like
8

Just wanted to chime in and thank everyone for working on this! We’re interested in adopting ReScript on my team, but the main point causing us to hesitate is the lack of a uniform documentation solution (e.g., docs.rs, hexdocs, jsr.io). A number of people on the team are brand new to FP, so we felt the current situation might be too frustrating.

2 Likes