@ristostevcev/bs-odoc

bs-odoc

Helper package to run odoc for bucklescript projects

Install

Install the package:

npm install --save-dev @ristostevcev/bs-odoc

And make sure you also have odoc installed:

opam install odoc

Optionally add the executable to your scripts in package.json:

{
  ...
  "scripts": {
    "clean": "bsb -clean-world",
    "build": "bsb -make-world",
    "watch": "bsb -make-world -w",
    "docs": "bs-odoc -g"
  },
  ...
}

For help, run bs-odoc -h.

It should work without configuring anything, but you need to have odoc installed. See the README for how to install odoc for bucklescript.

If you have odoc installed, it might not be on your PATH. Make sure you ran the opam command to fetch it's path info:

eval `opam config env`

Differences from bsdoc

Currently there is bsdoc, which is a more popular library currently. The reason why I'm still using and maintaining this project is due to some limitations of bsdoc (version 6.0.0-alpha):

• Heavy on dependencies since it's written in native ocaml and requires esy. This library is just a simple shell script wrapped in an npm package.
• Doesn't support linux or windows
• Doesn't offer the ability to add an index.mld file which is essential for writing nicer docs
• Doesn't set things up for github. The docs suggest adding a redirect file which is less than ideal. This library will prepare the docs so that they can be served by github immediately with no redirection.

That being said, it looks as though bsdoc is currently the official way to do things, and the popularity of the package would likely mean that these issues would get resolved eventually or upstream with odoc.

This library is mostly a hack really -- if you need slightly different behavior feel free to fork it and modify the script. This library will be archived once odoc and/or bsdoc are updated to work well with bucklescript (and hopefully dune) in a way that's identical to native.

License

See LICENSE