rescript-lang / bucklescript.github.io

BuckleScript's documentation site

The new BuckleScript docs live at https://rescript-lang.org. This repo is deprecated.

BuckleScript Website

This code is used to generate https://bucklescript.github.io. It pulls in files from docs/ and website/ to generate html files served on the site.

website/ contains the JS, CSS, images and other files (and blog, which contains some markdown files too, these are separated from docs/, not too important).

cd website && yarn && yarn start to start the development server & watcher.

Don't use yarn build. It's mostly for debugging.

In the end, we spit out normal HTML, with all the JS dependencies (barring a few critical ones) removed, including ReactJS itself. It's a full, static website, super lightweight, portable, unfancy but good looking. Works with JS turned off too.

Two special files:

• sidebars.json: lists the sections.
• siteConfig.json: some header and i18n configs.

During your development, most changes will be picked up at each browser refresh. If you touch these two files or blog/, however, you'll have to restart the server to see the changes.

Translations

The entire site can be translated via the Crowdin project. This repo only has the canonical english documentation. Don't manually edit things in i18n/.

Debugging

console.logs appear in your terminal! Since the site itself is React-free.

Building and Deploying

Changes from source branch are automatically picked into master branch by CI, then published. Translation download/uploads are still manual right now (needs API key, which @rickyvetter and @chenglou have).

bucklescript.github.io's Issues

Upstream glennsl's stuff

https://github.com/glennsl/bucklescript-ffi-cheatsheet and https://github.com/glennsl/bucklescript-cookbook

Reason snippets don't hide

When selecting OCaml syntax, some reason snippets don't hide.
Some (many ?) are incorrectly tagged with CSS class language-reasonml instead of language-reason with respect to main.css.

bs.raw Example produces compiler warnings

When I copy and paste the example code into the playground I receive compiler warnings:

File "", line 9, characters 20-21: Warning 20: this argument will not be used by the function. File "", line 9, characters 22-23: Warning 20: this argument will not be used by the function.

version: // Generated by BUCKLESCRIPT VERSION 2.2.4, PLEASE EDIT WITH CARE

https://reasonml.github.io/en/try.html?rrjsx=true&reason=DYUwLgBAhgJjEF4IG0CkAnKB3CBvAPgFAQQBmArgHYDGYAlgPaUAUUANBAEYCUexJEakwDODUADpgDAObMARAAsQwKWXQMAthEw4AUlABuUAMrV0dAA5gAhHO4BufiXThy6StAgBqLvwC+hPh+ALqOhLrCkjKscMwAjBwATNwOQA

Is this expected?

It would be interesting to have an .epub version of the docs. maybe we can use pandoc to generate something appropriate from the .md files.

It would be interesting to have an .epub version of the docs. maybe we can use pandoc to generate something appropriate from the .md files.

Explain Bucklescript's name mangling rule

Bucklescript has name mangling rules (as explained in genType's documentation) which are not explained at all in the official documentation. Can we add them? I can make a PR if the maintainers can tell me where to add them.

Copy over the setup from reasonml.github.io

We might want to have reasonml's translation infra set up or something. But doesn't matter too much for now.

We can keep things in sync through manual copy pasting for now.

Incorrect advice for ES6 default value import?

Hi, I just hit the error documented here: https://bucklescript.github.io/docs/en/import-export.html#import-an-es6-default-value. I was trying to import this: https://github.com/chenglou/react-spinner

I tried the suggested fix:

[@bs.module "react-spinner"] external spinner : ReasonReact.reactClass = "default";

However it didn't work for me, I kept getting the same error. What worked in the end was this:

[@bs.module] external spinner : ReasonReact.reactClass = "react-spinner";

I suspect (but I'm not sure) this is because the exported value is a class? If we can identify the cause of the problem we can update the documentation.

Mention `[@@bs.get]` on page about objects

https://github.com/BuckleScript/bucklescript.github.io/blob/source/docs/object.md

Please, it was rather difficult to google how to access a field of an object that is not yet created.

Algolia still wrong

@rickyvetter I think it's still crawling the Manual page

Fix typo Js.Json.object_

There is a typo (missing c in object word) on page https://bucklescript.github.io/bucklescript/api/Js.Json.html

val object_ : t Js_dict.t -> t
object_ dict makes a JSON objet of the Js.Dict.t dict

to

val object_ : t Js_dict.t -> t
object_ dict makes a JSON object of the Js.Dict.t dict

Wanted to submit a pull request but did not found the file in this repo.

https://www.rust-lang.org/en-US/whitepapers.html for BuckleScript

some suggestions

1. how to create links to some section?
   for example Interop/Embed Raw JavaScrpt section

2. The syntax highlighting for OCaml code seems not correct, let keyword is colored

3. For interop examples, can we always make it editable so that both ocaml/js code would displayed

Doc change to make FFI bindings easier to learn

Currently the FFI docs do not show the generated Javascript, which leaves the reader guessing and makes bindings more difficult to learn. It would help if each FFI binding construct consistently had:

• bs / reason syntax including usage of the binding
• corresponding generated or equivalent javascript

(you might even put the generated js first, since that is the reader's initial intent)

Example borrowed from Glennsl's cheatsheet

Toggling REASON/OCAML doesn't seem to work

Toggling buttons on the top of the pages doesn't seem to work.

Document pages are showing both Reason and OCaml no matter which language you choose on the top toggling menu.

I've tested this with my iOS Safari and Chrome and also macOS Safari and Chrome and they show all same results.

Fix documentation

#43

object.md out of date, maybe?

Hello! I'm not sure if this is something I'm doing wrong, or if docs/object.md is out of date so I didn't dare suggest a PR, but the document shows an example and mentions: "Js.Dict is simply backed by a JS object. The entire API uses nothing but ordinary BuckleScript externals, so the whole API disappears after compilation. There should be no mention of Dict anywhere in the generated output."

However, with BS 6.x I cannot reproduce the simplicity of the example, and instead get from:

external testobj : string Js.Dict.t = "testobj" [@@bs.val]
(* later: *)
  ( match Js.Dict.get testobj "test" with
  | None -> Js.log "not found"
  | Some _ -> Js.log "found"
  )

…to:

var match = Js_dict.get(testobj, "test");  // <-- not testobj["test"]
if (match !== undefined) {
  console.log("found");
  return /* () */0;
} else {
  console.log("not foud");
  return /* () */0;
}

6 broken links and a couple of other issues

A couple of links are broken here: https://www.techatbloomberg.com/blog/bucklescript-1-0-release-arrived/

Hello world
examples of calling JS libraries
The playground
FFI

The link for the FFI changed, so it directs now to the header of the manual as a fallback,
instead to the FFI section

Plus, the Github button on this page leads to a complete different repo,
namely that one of Bloomberg instead of the Bucklescript one.

When somebody likes to visit your Homepage at https://bucklescript.github.io, redirects that to the manual instead to the actual Homepage, the link to the Blog does an intermediate step to a pointless page between and there is a space missing on the homepage.

Add prettier to ensure consistent formatting

Firstly, I would like to give a massive thanks to the BuckleScript team for an amazing project!

I had just cloned this repo as I want to make some improvements to the docs site, and I realized that when I went to edit any of the .md files, my editor was messing with the current formatting because I have the prettier extension installed. You have probably heard of prettier by now, but if you haven't, have a look at their website here.

I think prettier would make a great addition to the docs siterepo as it would format both the .md files that contain the documentation text, as well as the .js, .css and .html files that are used to build the site.

This would be useful because, from a quick look into the source files, I can see some inconsistencies in formatting. For example, sometimes trailing commas are used and sometimes they are not. It would also mean that possible new contributors (Like me!) wouldn't have to worry about how the project wants their files formatted, the editor / project would do it for me.

This could be done in two ways (Or both for better DX):

1. A prettier config file (.prettierrc) could be created at the root of the project, and a contributor's editor could recognize the file and format the files respecting these settings. The benefit of this approach is that it doesn't require much change. However, the issue is that if the contributor is not using the prettier plugin in their editor, or they just don't have one available, the code could be formatted wrong, and it would have to be changed before being merged.
2. A pre-commit hook could be added that runs prettier on the files that a contributor has staged. This would ensure that files commited to the repo were formatted correctly. The downside is that it adds a little bit more complexity to the project.

As mentioned above, I think that both 1 and 2 could be done together, so that when the contributor is developing, their editor will format the code correctly if they have the plugin installed, but if they don't then it doesn't matter because the pre-commit hook will format the files correctly anyway.

From what I have read of the source files, I think a config such as this would fit the project (Please correct this if it doesn't line up with the projects formatting style):

{
  "printWidth": 80,
  "semi": true,
  "singleQuote": false,
  "useTabs": false,
  "tabWidth": 2,
  "bracketSpacing": true,
  "trailingComma": "none",
  "proseWrap": "always"
}

Thanks for reading!

Add more languages

Let's add:

• japanese
• portugese
• russian

cc @rickyvetter

Document using bsc to generate interface file

It uses the outcome printer though, so there are BS-EXTERNAL tags everywhere