Re: ocamldoc generation and packed files

[Thomas Gazagnaire <thomas.gazagnaire@xxxxxxxxx>]

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