Re: ocamldoc generation and packed files

[Anil Madhavapeddy <anil@xxxxxxxxxx>]

Thanks Thomas, that looks very useful and definitely better than the script in 
tree at the moment.

One question: ocp-pack also requires that the list of files be passed in 
dependency order, or else the resulting pack file will not compile.  Have you 
tried to integrate it as an ocamlbuild rule, so that it can automatically sort 
the input modules before generates the packed file / functor?

Anil

On 12 Aug 2011, at 20:01, Thomas Gazagnaire wrote:

> It will be anounced quite shortly on the ocaml mailing list, so I can
> give you the link to ocp-pack :
> 
> http://www.ocamlpro.com/code/2011-08-10-ocaml-pack-functors.html
> http://www.ocamlpro.com/files/ocp-pack-1.0.0.tar.gz
> 
> It should help you to pack modules easily and have a working doc.
> 
> --
> Thomas
> 
> 2011/7/28 Anil Madhavapeddy <anil@xxxxxxxxxx>:
>> That tool will be very useful! I've committed the 'make doc' target. The 
>> output is still pretty dirty as we don't use the documentation tags 
>> properly, but I'll go through adding .mli files and adding proper 
>> documentation on the more stable interfaces.
>> 
>> It would be quite nice to eventually have a single documentation output for 
>> all the backends, with an addition section saying 'only present in Xen' or 
>> 'only present in Node'. I think that should be possible by parsing the 
>> ocamldoc dump outputs, but something for the future!
>> 
>> Anil
>> 
>> On 27 Jul 2011, at 16:56, Thomas Gazagnaire wrote:
>> 
>>> We have as well a program which pack together ML files (and is able to 
>>> functorize packs as well...) it is not released yet, but I guess we can 
>>> open-source it shortly.
>>> 
>>> But I think overriding the default rule for ocamldoc+pack in ocamlbuild is 
>>> sufficient for now on so you should push your patch :-)
>>> 
>>> Thomas
>>> 
>>> On Jul 27, 2011, at 5:36 PM, Anil Madhavapeddy wrote:
>>> 
>>>> I'd really like to generate ocamldoc (HTML/PDF) of all the various 
>>>> libraries so that it's easier to learn Mirage (and support editor 
>>>> auto-completion, etc).
>>>> 
>>>> The big problem is that ocamldoc doesn't support packed modules, and we 
>>>> use packing quite extensively (in Net, Http, Block, etc).
>>>> 
>>>> So I've hacked up an ocamlbuild target that concats together the *source* 
>>>> ML files from an .mlpack and uses that to generate the ocamldoc for the 
>>>> standard library, with one set of HTML files generated per backend (Xen, 
>>>> Net-Direct, Net-Socket, and so on).
>>>> 
>>>> The issue is that these rules are a little grim: everywhere where we have 
>>>> a .mlpack file at the moment, we need to override that rule to generate a 
>>>> concatenated ML file that is used for ocamldoc (but not for actual 
>>>> compilation, since line numbers get lost since those aren't preserved when 
>>>> converting from ML files into a single big one).
>>>> 
>>>> Does anyone have a better solution for ocamldoc and packed files? All of 
>>>> the grimness here is hidden away in the ocamlbuild rules, so I'm inclined 
>>>> to just commit this patch, and perhaps see about adding -pack support into 
>>>> ocamldoc at a later stage (there's an open bug in Mantis somewhere).
>>>> 
>>>> Dave, do you use pack in XAPI, and/or ocamldoc?  I wonder if everyone else 
>>>> (like Core) also have their own swanky 'cat ML files into one' script 
>>>> too...
>>>> 
>>>> -anil
>>> 
>> 
>> 
>