So I just tried¹, and the failure is as follows:

$ ocamlbuild -tag use_ocamldoc test.cmxs
+ /home/gasche/.opam/4.02.3/bin/ocamlopt.opt -shared -I +ocamldoc ocamldoc.cmxa test.cmx -o test.cmxs
File "_none_", line 1:
Error: Cannot find file ocamldoc.cmxa

It looks like the tag use_ocamldoc expects a file ocamldoc.cmxa to exist, providing library support for ocamldoc plugins, and it does not seem to exist -- it seems that the preferred way to use ocamldoc plugins is to use "ocamldoc.opt -g foo.cmxs", with ocamldoc libraries already linked inside ocamldoc.opt. So just using

ocamlbuild -cflags -I,+ocamldoc test.cmxs

works and seems to do what you expect.

It goes without saying that this is not a perfect long-term solution, as it assumes that ocamldoc libraries are distributed with the stdlib. It would be cleaner to have an ocamldoc package for them (just like ocamlbuild has a dummy ocamlfind package indicating the location of its library files), but it seems that this is not currently the case. It would be nice (but not super-high priority) to have such a dummy package in ocamlfind in the future, so that you can just do

ocamlbuild -use-ocamlfind -package ocamldoc test.cmxs

¹: The most time-consuming part was finding the code of a ocamldoc plugin to compile, as the documentation examples are incomplete. Next time, feel free to provide a tarball with a minimal example to reproduce.

On Fri, Dec 18, 2015 at 5:14 PM, Armaël Guéneau <armael.gueneau@ens-lyon.fr> wrote:

Hi list,

I'm wondering how one should compile ocamldoc custom generators using
ocamlbuild.

First, the ocamlbuild manual
(https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags-)
says that the [use_ocamldoc] tag is deprecated; and that a corresponding
ocamlfind package should be used instead. Is there such a package for ocamldoc?
I did not found one.

Then, I did not manage to build the plugin into .cma/.cmxs files directly using
ocamlbuild. My command line was something along these lines:

ocamlbuild -use-ocamlfind -tag use_ocamldoc -package compiler-libs plugin.cmxs

When trying to build plugin.cma/plugin.cmxs, ocamlbuild complained that "Cannot
find file ocamldoc.cma/ocamldoc.cmxa" (respectively). However, I can build
plugin.cmo/plugin.cmx using the same command line, then create the .cma/.cmxs
manually using ocamlc/ocamlopt - which I ended up doing.

Is there a better way to do so? If the whole process can be improved (how?), I
would be happy to write the required patches/documentation.

— Armaël