odoc

The documentation compiler for OCaml and Reason.

1. What is odoc?
2. Getting Started with odoc
3. How does odoc work?
4. Using odoc
5. Integrating odoc into your Build System
6. Understanding odoc Internals
7. Contributing to odoc

What is odoc?

odoc is not your ordinary documentation tool.

It's built from the ground up to be build-tool friendly, and it focuses on parallelism and caching. Instead of source code, it works with compilation units; that is, it works on compiler outputs and turns them into compiled documentation, which then becomes gorgeous HTML.

Compiled documentation appears in the form of .odoc files, which consist of an intermediary representation that is currrently internal and subject to change.

A regular odoc execution transforms .cmt, .cmti, and .mld files into .odoc files, and then turns those into .html files. Roughly like this:

cmti_and_mld_files |> compile_to_odoc |> compile_to_html

This means that an intro.mld file will be compiled to page-intro.odoc which in turn will become intro.html.

Similarly, a Game.cmti will be compiled to Game.odoc which in turn will become Game/index.html.

Getting Started with odoc

You can install odoc today through opam:

opam install odoc

...using OCaml

If you want to use odoc on the packages you have installed in your opam switch type:

opam install ocaml-manual odig
odig doc

When you are developing the easiest way to use odoc right now is by having Dune drive it. This command should work in most Dune projects out of the box:

dune build @doc

The generated docs can be found at ./_build/default/_doc/_html/index.html.

...using BuckleScript

While the BuckleScript/Reason toolchain relies on npm, odoc at the moment needs to be used from a working OCaml toolchain.

This means we follow the same installation than above, but using the 4.02.3+buckle-master version of the OCaml compiler.

$ opam switch 4.02.3+buckle-master
$ eval `opam config env`
$ opam install odoc

Now with that working, we can point odoc to the path where BuckleScript saves the compiled code that we can use to generate our documentation. This path is $root/lib/bs.

In there you'll find your .cmt and .cmti files.

You can now compile each one of them from .cmt[i] to .odoc and from .odoc to .html.

The following script can help you get started:

#!/bin/bash

readonly PKG=$1
readonly DOCS=$2

readonly ODOC=$(which odoc)
readonly LIB=./lib/bs/src

readonly CMT_FILES=$(find ${LIB} -name "*.cmti")
readonly ODOC_FILES=$(echo ${CMT_FILES} | sed "s/cmti/odoc/g")

echo "<< Compiling docs..."
for file in ${CMT_FILES}; do
  ${ODOC} compile \
    -I ${LIB} \
    --pkg=${PKG} \
    ${file}
done
echo ">> Done!"

echo "<< Generating HTML..."
for file in ${ODOC_FILES}; do
  ${ODOC} html \
    -I ${LIB} \
    -o ${DOCS} \
    --syntax=re \
    --semantic-uris \
    ${file}
done
echo ">> Done!"

And you can call it like:

$ ./mk-docs.sh MyPackageName ${path_to_docs_folder}
<< Compiling docs...
>> Done!
<< Generating HTML...
>> Done!