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?

score 3 · Answer 1 · answered Jun 29 '13 at 10:09

The problem is described in the following bugreport. Handling -pack inside ocamldoc requires an implementation effort that the maintainer is not motivated to perform, and so far nobody stepped up to contribute a patch for this feature.

In the meantime, you can easily copy your foo.mlpack file into a foo.odocl generating the documentation of the separate submodules. That's only an imperfect workaround as the doc will talk about X rather than Foo.X, but that's a least-effort solution.

score 2 · Accepted Answer · answered Jun 29 '13 at 10:25

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)

Using ocamldoc with packs

2 Answers2