Using ocamldoc with packs

Question

I have an ocamlbuild project which includes some files in a subdirectory with an .mlpack file listing them.

e.g. I have a file support/logging.ml which defines the module Support.Logging. The _tags file says "support": for-pack(Support).

This all builds and runs fine. But how can I generate docs for this using ocamldoc?

The most recent post I found was ocamldoc generation and packed files from 2011, which suggests using ocp-pack to generate one large .ml file and pass that to ocamldoc. However, that doesn't take into account the build order, so the generated module doesn't work due to forward references.

What's the best way to handle this?

Answer 1

Here's the solution I'm now using in my Makefile. It does work, and cross-references into the Support module work:

doc:
    ocp-pack -o support.ml.tmp support/logging.ml support/common.ml support/utils.ml support/basedir.ml support/qdom.ml support/system.ml
    echo '(** General support code; not 0install-specific *)' > support.ml
    cat support.ml.tmp >> support.ml
    rm support.ml.tmp
    $(OCAMLBUILD) 0install.docdir/index.html
    rm support.ml

It's hacky because:

• You have to list the support.ml files in build order, by hand
• The Makefile adds the doc comments for Support (otherwise, it takes the description of the first sub-module, which you don't want)