Re: [Caml-list] Ocamlbuild + Ocamldoc troubles

[DooMeeR <d@doomeer.com>]

> I'm using Ocamlbuild to manage the compilation of a library.  The
> myocamlbuild.ml plugin I'm using is a slight variation of the one found on
> the Wiki and that adds support for Findlib [1].  Even though the actual code
> compilation is working fine, I'm having problems getting it to correctly
> invoke Ocamldoc to produce the API docs.
> 
> On the project's root directory I have the plugin and a '_tags' file that
> simply says that the 'lambdoc' (contains code) and 'apidoc-src' (contains
> txt files with intro and tutorials for API doc) directories should be included:
> 
> <lambdoc>: include
> <apidoc-src>: include
> 
> Also on the root directory I have a 'lambdoc.mlpack' file containing all the
> modules that should be packed together (the modules themselves are inside the
> 'lambdoc' directory), and a 'lambdoc.mllib' file with a single line 'Lambdoc'
> that signals that the pack should be made into a library.  In addition, I
> modified the plugin so that an invocation of ocamldoc would add the '-intro'
> option to Ocamldoc:
> 
> let ocamldoc_opts = S [A"-intro"; A"intro.txt"]
> 
> And flagged it accordingly in the After_rules:
> 
> flag ["ocaml"; "doc"] ocamldoc_opts;
> 
> Unfortunately this isn't working.  When I invoke 'ocamlbuild
> lambdoc.docdir/index.html', Ocamldoc always complains it can't find the
> intro.txt file.  Moreover, if I forgo the intro modifications to the plugin,
> even though the ocamldoc invocation succeeds, the lambdoc.docdir directory
> contains only skeleton Ocamldoc files, ie, no actual generated API.
> 
> So my questions are on how to get Ocamlbuild to generate the API documentation
> in this context, and on how can external txt files also be included.

I only read your problem very quickly as I'm kind of busy, so please 
excuse me if I say something very stupid ;)

So, ocamldoc doesn't find "intro.txt". This is because this file is not 
copied into the _build directory by ocamlbuild. You need to explain to 
ocamlbuild, in your plugin, that your target (lambdoc.docdir/index.html) 
depends on "intro.txt", otherwise ocamlbuild won't copy the file. Even 
if you copy the file yourself into the _build directory, ocamlbuild 
might delete it.

If I remember correctly there is a function of the plugin API, called 
"dep" if I'm not mistaken, which does exactly this.

I can develop this in more details tomorrow if you need.

-- 
Romain Bardou