[Caml-list] Ocamldoc and multiple packages

[Alexey Rodriguez]

Dear list,

I am trying to build ocamldoc documentation for an ocaml project that
contains multiple packages (collections of modules built using
-for-pack and -pack). My current setup generates documentation for
each package but it won't generate hyperlinks to modules in other
packages (module not found errors). I tried using the -load and -dump
commands to allow ocamldoc see the ocamldoc-results of the referred to
package, but I still get problems. I suspect that the problem arises
because ocamldoc does not have a -pack option, so it always sees
modules in a flat way. So if you have package Pack1 with module A, and
module B in Pack2 which refers to Pack1.A.t, ocamldoc cannot solve
this reference because it does not know that module A is inside
another module called Pack1.

The solutions I see right now seem to involve more effort than I am
willing to spend. So, before I embark on a task that might take too
long I would like to ask for tips on this. How do you perform ocamldoc
generation for projects with multiple packages? Thanks!

Cheers,

Alexey

_______________________________________________
Caml-list mailing list. Subscription management:
http://yquem.inria.fr/cgi-bin/mailman/listinfo/caml-list
Archives: http://caml.inria.fr
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
Bug reports: http://caml.inria.fr/bin/caml-bugs

[Ashish Agarwal]

I don't know the answer but you might try using ocamlbuild's mlpack and
odocl features, and see how it does it.

[Bertrand Jeannet]

> ------------------------------------------------------------------------
>
> Subject:
> [Caml-list] Ocamldoc and multiple packages
> From:
> Alexey Rodriguez <mrch...@gmail.com>
> Date:
> Fri, 11 Sep 2009 17:47:09 +0200
> To:
> OCaml List <caml...@inria.fr>
>
> To:
> OCaml List <caml...@inria.fr>

>
>
> Dear list,
>
> I am trying to build ocamldoc documentation for an ocaml project that
> contains multiple packages (collections of modules built using
> -for-pack and -pack). My current setup generates documentation for
> each package but it won't generate hyperlinks to modules in other
> packages (module not found errors). I tried using the -load and -dump
> commands to allow ocamldoc see the ocamldoc-results of the referred to
> package, but I still get problems. I suspect that the problem arises
> because ocamldoc does not have a -pack option, so it always sees
> modules in a flat way. So if you have package Pack1 with module A, and
> module B in Pack2 which refers to Pack1.A.t, ocamldoc cannot solve
> this reference because it does not know that module A is inside
> another module called Pack1.
>
> The solutions I see right now seem to involve more effort than I am
> willing to spend. So, before I embark on a task that might take too
> long I would like to ask for tips on this. How do you perform ocamldoc
> generation for projects with multiple packages? Thanks!
>
> Cheers,
>
> Alexey
>

I wrote very recently a small script that packs source modules into a
big module, and takes care of ocamldoc convention, which is to interpret
in each file the first (** *) comment as the title associated to the module.

I am very bad at sh and gawk script, so the result (given below) is not
very elegant...

It would of course be better (and much more robust) to have a direct
support in ocamldoc.

Bertrand

-----------

#/bin/sh

# command line (very primitive...)
if test $1 != "-o"; then
echo "ocamlpack: usage: ocamlpack -o outputmodule -title <str>
module1 module2 ..."
exit -1
fi
shift
out=$1
shift
if test $1 != "-title"; then
echo "ocamlpack: usage: ocamlpack -o outputmodule -title <str>
module1 module2 ..."
exit -1
fi
shift
outtitle=$1
shift

# prepare output
/bin/rm -f $out.ml $out.mli
echo "(** $outtitle *)">$out.ml
echo "(** $outtitle *)">$out.mli

# iterate on input module,
for i in $*; do
name=$i
# 1.A Look for the first (** *) comment, and output it to out.ml
# (see ocamldoc convention)
gawk -v name=$name '
BEGIN {
start=1
# isolate module name from path/modulename
nb = split(name, dirname, "/")
name = dirname[nb]
if (RLENGTH>0)
name = substr(name,RINDEX,length(name)-RINDEX)
# Capitalize the module name
hd = toupper(substr(name,1,1))
tl = substr(name,2,length(name)-1)
}
# Look for the first (** *) comment, and output it
{
if (start==1) {
match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ )
if (RLENGTH>0){
start=0
title=substr($0,RSTART+4,RLENGTH-7)
print "\n(** {1 Module [",hd tl "]:",title "} *)\n"
print "module",hd tl,"= struct"
}
}
}
END {
if (start==1) {
print "\n(** {1 Module [",hd tl "]} *)\n"
print "module",hd tl,"= struct"
}
}
' $i.ml >>$out.ml
# 1.B Output the rest of name.ml to out.ml
gawk -v name=$name '
{
if (start==1) {
match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ )
if (RLENGTH>0)
start=0
else
print $0
}
else
print " ",$0
}
END { print "end\n" }
' $i.ml >>$out.ml

# 2.A Look for the first (** *) comment, and output it to out.mli
gawk -v name=$name '
BEGIN {
start=1
nb = split(name, dirname, "/")
name = dirname[nb]
if (RLENGTH>0)
name = substr(name,RINDEX,length(name)-RINDEX)
hd = toupper(substr(name,1,1))
tl = substr(name,2,length(name)-1)
}
{
if (start==1) {
match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ )
if (RLENGTH>0){
start=0
title=substr($0,RSTART+4,RLENGTH-7)
print "\n(** {1 Module [",hd tl "]:",title "} *)\n"
print "module",hd tl,": sig"
}
}
}
END {
if (start==1) {
print "\n(** {1 Module [",hd tl "]} *)\n"
print "module",hd tl,": sig"
}
}
' $i.mli >>$out.mli
# 2.B Output the rest of name.mli to out.mli
gawk -v name=$name '
{
if (start==1) {
match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ )
if (RLENGTH>0)
start=0
else
print $0
}
else
print " ",$0
}
END { print "end\n" }
' $i.mli >>$out.mli
done

[Alexey Rodriguez]

Hi Edgar,

On Sat, Sep 12, 2009 at 5:27 PM, Edgar Friendly <thele...@gmail.com> wrote:
> Alexey Rodriguez wrote:
>> Dear list,
>>
>> I am trying to build ocamldoc documentation for an ocaml project that
>> contains multiple packages (collections of modules built using
>> -for-pack and -pack).
>

> Batteries also has this problem, and does a decent job of solving it
> through methods that are too complicated for me to explain in the margin
> of this email. �:) �Read the source.

I had a quick look at batteries. I understood that the build system
makes one ocaml source file with the module structure of the whole
project, which ocamldoc should be able to parse. This solution looks
reusable (at least the idea does not seem too complex to implement).
Thanks for the tip!

Thanks to anyone else who replied.