Thoughts on unifying ReasonML Documentation

#1

The problem at hand

ReasonML documentation is currently “split” between ReasonML and BuckleScript. In the discord channel, I often see questions about Reason being answered by referring to documentation written for BuckleScript. All of the documentation for Belt and Js appears to be in BuckleScript format. Even the ReasonML API links, such as Array have declarations in ReasonML but the explanations in BuckleScript style (or possibly the old no-parentheses ReasonML style).

This reminds me of the situation in the early days of Elixir, where a lot of the documentation referred you to Erlang docs.

Solving the problem

Elixir has developed its own documentation, generated from its source, which is separate from the Erlang code. For example, the source for Elixir genServer is totally different from the Erlang gen_server documentation – which is not generated from the source code. This sort of solution requires a lot of effort.

It would be far preferable to generate both ReasonML and BuckleScript documentation from a single source. docre helps greatly in this regard. For example, this is the conversion of Belt_List, which does a respectable job. It generates quite a few Unable to refmt code with a syntax error because (as per the author of docre) “…lots of the examples assume they’re in a top-level, which doesn’t work with docre”

The next step, as I see it, would be to modify the existing BuckleScript documentation so that the examples are all translatable via docre, and yes, I am willing to assist with this.

#2

It would be nice if the BuckleScript documentation had a way to toggle OCaml/Reason syntax instead of showing both options–generally speaking, I need to hide as much complexity as possible while I’m learning something new, and this could help reduce the mental overhead for newcomers like me. (My experience when reading the docs usually goes something like: “Oh, here’s the example code. Wait, this doesn’t make sense. Oh, it’s OCaml. [skip down] Ah, here’s the Reason code that I’m trying to learn.” Multiply times number of code samples I read.)

About documentation, immutability, first-class functions and dynamic and static environments
#3

I definitely agree that the API docs for Reason and Bucklescript are pretty harsh to read, especially if you’re new to Reason. Not hard in the syntax but the visual organization of the APIs themselves.

I wonder who’s working on this if anyone

#4

@dangdennis Yea, the docs look harsh, I’m really not used to that coming from other languages.

I rethemed the standard llbrary docs since I couldnt stand how they look, if that helps you a bit: (though only on 4.07 and its still incomplete - no submodules yet): https://www.streamingspring.com/ocaml/docs/
It has a sidebar to quickly move between modules and functions and also has a search.

#5

Wow that actually looks way better. The function signatures are much clearer too.

Didn’t look at your source code yet but did you generate this or manually ported it over?

#6

Thanks.

It’s generated. I used lambdasoup to parse it and generate json. Then I used bs-json and bucklescript-tea to encode and display it how I want.

It’s kind of a little heavy right now since it downloads the whole json docs to the front end. I may think about serving it from the server side in the future.

#7

Awesome. Can you add a service worker to users can cache the page? Aka me! Haha

#8

Hmm… I don’t have any experience with service workers, and didn’t have any current plans to add it, but who knows?

It’s at least served through a CDN, so its cached that way, but I’m still actively updating it, so it doesn’t really matter that much, since you’ll have to keep getting fresh copies when I do.

I’m now working on trying to see how to map the submodules in and whats the best way to do that. There’s so many pages, especially with types and stuff, I’m not sure I want to parse all of them yet.

I kinda just wanted better looking docs, but I’m still new to the language, I didn’t realize there so much. I don’t really have too much time to spend on this, we will see where I get to I guess. Or maybe what I end up needing to use will force me to add more things in.

#9

Wouldn’t it be better to just contribute a css for the doc upstream?

#10

It’s possible to just use css, but it would only style the standard structure of the page.

That would still be hard since the html has little structure and tags incorrectly arranged. For example, there are h3 sometimes that are same as div class=“h3” and other completely non-sensical things. It looks like the official docs are generated, but not done so that correctly. Some “info” sections are not correctly grouped together as well and many other problems. It would be hard to do that with all just Css selectors (but may be possible).

Also, you wouldn’t be able to add the features like having a sidebar where you can quickly navigate between modules or a search bar with results.

I am open to suggestions to making this easier though.

#11

It’s possible I think, though not trivial, to write a generator plugin to do all of this. This is the generator plugin that generates BuckleScript’s API docs. It even had a sidebar like yours, but Bob, in his infinite wisdom, didn’t see the point and removed it (as well as molesting the generator in other ways).

#12

Hmm… seems complicated. Sorry, still many things in the language I don’t understand yet.

I’ve thought about modifying the ocaml doc generator before, but thought it would be too complicated to understand.

In the mean time, I’ve updated mine with all the modules, submodules, functors, module types, etc…
I’m not going through all of them to check everything though, too many.

Unfortunately though, it grew almost twice as big, so the initial load is it a bit longer.

#13

This is something that really confused me when I started learning ReasonML.

e.g. I wanted to split a string, so I started by googling: Reasonml string split

The first result was this: https://reasonml.github.io/api/Str.html#VALsplit But when I tried using it,

The module or file Str can't be found.
Are you trying to use the standard library's Str?
If you're compiling to JavaScript, use Js.Re instead.
Otherwise, add str.cma to your ocamlc/ocamlopt command.

The second result I got was this one: api/String.html but there was no split method on the page.

In the end, I found this: https://bucklescript.github.io/bucklescript/api/Js.String.html#VALsplit

I knew Bucklescript was related to reason, but as examples were in a different language, it seemed weird.

It’d be very helpful, if there was an article in the docs explaining ReasonML-Bucklescript relationship and how to find docs/type signatures for std library functions like Js.String.split.

If there’s already existing resource about this, please let me know.