Ocamlbuild + Ocamldoc troubles

Ocamlbuild + Ocamldoc troubles

[Dario Teixeira]

Hi,

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.

Thanks in advance for your attention!
Best regards,
Dario Teixeira

[1] http://brion.inria.fr/gallium/index.php/Using_ocamlfind_with_ocamlbuild

Re: [Caml-list] Ocamlbuild + Ocamldoc troubles

[DooMeeR]

> 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

Re: [Caml-list] Ocamlbuild + Ocamldoc troubles

[Dario Teixeira]

Hi,

> 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.

Thanks for the reply.  Ideally one should be able to specify
that info in the _tags file and/or with other special files.
And I reckon that Ocamlbuild probably already supports that.

By the way, I have managed to get Ocamlbuild to invoke Ocamldoc
for the source code files only (no intro or tutorials) by
creating a lambdoc.odocl file whose contents are the same as
lambdoc.mlpack's.  However, the compilation fails with a
mysterious "analyse_module: parsetree and typedtree don't match"
error:

+ ocamlfind ocamldoc -dump lambdoc/document_ast.odoc -package extlib -package ocsigen.xhtml -package pcre -package sexplib -package threads -package unix -package xml-light -I lambdoc -I lambdoc/readers -I lambdoc/writers -I lambdoc/readers/lambtex_reader_impl lambdoc/document_ast.ml
analyse_module: parsetree and typedtree don't match.
1 error(s) encountered
Command exited with code 1.

Any ideas?

Cheers,
Dario