voodoo

Voodoo uses odoc to generate the package documentation for OCaml.org

🚀 Getting started

voodoo is intended to be used as part of an ocurrent pipeline, for example via ocaml-docs-ci.

You need opam, you can install it by following Opam's documentation.

With opam installed, you can install the dependencies in a new local switch with:

make switch

Then, build the project with:

make build

voodoo is run in three successive steps detailed below.

🌱 1. Prepare the packages: voodoo-prep

To prepare the packages just run:

voodoo-prep [-u <UNIVERSES>]

Where <UNIVERSES> is a comma-separated list of packages and universes pkg1:unv1,pkg2:unv2,....

When you don't provide a universe explicitly, each package installed in the current switch will be prepared (prepped) for the compiling step.

This creates an ad-hoc directory structure and populates it with .cmt, .cmi, .cmti, .mld from the current switch. The ocamlobjinfo of the .cma files are also copied, as well as the documentation files such as .md, .html and others (such as the opam files).

💦 2. Compiling and linking the packages: voodoo-do

Once voodoo-prep has run, voodoo-do is able to process packages. Simply run:

voodoo-do -p <PACKAGE> [-b] [--failed]

This command runs odoc compile and odoc link on the package specified after -p. If the --failed flag is set, a file named failed containing "failed" is also generated.

If the packages are processed out of dependency order, voodoo-do will alert that there are missing dependencies.

voodoo-do -p odoc -b
...
Missing dependency: Stdlib c21c5d26416461b543321872a551ea0d
...

In this case, we need to run voodoo-do -p ocaml-base-compiler -b first.

Note that when being used in this mode, the -b flag should always be passed to voodoo-do.

At this point, to view the output, use odoc to generate the support files (mostly: copying highlight.js from https://highlightjs.org and odoc.css):

cd ..
odoc support-files -o html

You can load the package index in your browser:

open ./html/p/<PACKAGE>/<VERSION>/doc/index.html

🌳 3. Rendering the packages: voodoo-gen

Once voodoo-do has run, you can generate the website with the documentation, run:

voodoo-gen -o <DIR> [-n <PACKAGE>] [--pkg-version <VERSION>]

This command runs odoc html-generate to render the files of the specified package as html.

You can serve it with:

opam install dream-serve
dream-serve ./html

Load the package index in your browser:

$ open http://localhost:8080/p/<PACKAGE>/<VERSION>/doc/index.html

🏇 TLDR

1. Install packages to be documented in the current switch using opam
2. Create _generated directory
3. Run voodoo-prep. This creates the ad-hoc directory structure inside _generated and populates it with .cmt, .cmi, .cmti, .mld from the current switch. Documentation files such as .md, .html and others are also copied.
4. Run voodoo-do on each package to compile and link the odoc files.
5. Run voodoo-gen to create the _generated/output directory and generate the HTML files.
6. Run odoc support-files -o _generated/html to add css and styling to the html subdirectory
7. Serve _generated/html

voodoo-* commands must be called from the _generated directory.

mkdir _generated
cd _generated
opam exec -- dune exec -- voodoo-prep
opam exec -- dune exec -- voodoo-do -p <PACKAGE> -b
opam exec -- dune exec -- voodoo-gen -o output
cd ..
odoc support-files -o _generated/html
dream-serve _generated/html