Odoc usage documentation (sans dune)? [with notes on what I learned in my little foray]

Ecosystem
,
1

I’m trying to figure out how to use odoc without dune, and can’t find any (heh) documentation on that. Have I overlooked it somehow?

If the answer is “there isn’t any”, that’s OK: I’ve reverse-engineered based on dune’s _build/log file before, and I’ll do so this time. But I figured I’d ask, before I dive into the logfile.

ETA: For anybody who comes after me, some notes:

(1) read the “odoc --help” and “odoc compile --help”, “odoc html --help” etc. These are the real documentation for odoc, it would seem.

(2) Suppose you have a set of Ocaml files you wish to build documentation for. Compile them with the “-bin-annot” switch, generating “.cmt” and “.cmti” files. Apparently if there’s a .cmti file, the .cmt file is superfluous.

(3) then invoke odoc. I did it thus (and I’m sure there’s more to learn as I go along):

odoc compile --package foo -o foo.odoc boo.cmti
odoc html -o doc foo.odoc

This generated ./doc/foo/Boo/index.html. with the expected contents.

1 Like
2

It’s not great but odig doc odoc has a bit more, sample here and for example this page.

3

Yaaaas! That shell-script in the first link. Just what I always wanted! Thank you!

4

I vaguely remember some things were wrong with that shell script, but I can’t exactly remember what. The documentation I perused for writing the odig odoc driver consisted in pestering @trefis for the fine details.

5

Ah yes I think the problem is that before you odoc compile cmti you have to compile the .odoc file for the modules mentioned by odoc compile-deps cmti and make sure they are visible via -I.