Two questions on OCamlDoc

Two questions on OCamlDoc

[David Teller]

     Hi everyone,

 I'm currently toying with OCamlDoc, with very little success. I'm
attempting to do two things:
* getting OCamlDoc to understand that some modules (which I can modify)
contain the documentation for some other modules (which I can't) replace
some modules with others
* inlining the documentation for modules in modules which import those.

I need a little help.

Let me detail this.

*** Documentation replacement ***
My project uses modules M_lib1, M_lib2... which come from a variety of
libraries. For each of these modules, I have created  a module
M_lib1_with_doc, M_lib2_with_doc, which imports the corresponding
library module but tailors the documentation to my project. However, for
technical reasons of mechanical generation, assuming that M_lib1 refers
to M_lib2, M_lib1_with_doc still refers to M_lib2 instead of referring
to M_lib2_with_doc. Consequently, when generating the documentation of
M_lib1_with_doc, ocamldoc doesn't link the generated pages to the
documentation of M_lib2_with_doc but rather attempts to link it to
M_lib2 (and fails, as expected).

Now, I could rework the mechanical generation of my modules and in time,
I will. However, for the moment, I'm looking for a purely OCamlDoc-based
solution. I'd like to be able to ask OCamlDoc to please consider every
reference to M_lib2 as actually meaning a reference to M_lib2_with_doc.

I have tried to override method [text#html_of_Ref], without much
success. Is there a simple solution for this?

*** Inlining modules ***
I have a few modules whose sole role is to include one or two existing
modules. By default, when meeting [include], OCamlDoc, ocamldoc only
generates a link from the container module to the inlined module. In
this case, I'd rather want the whole documentation of each of these
modules to be inlined.

Is that possible?

Thanks in advance,
 David

-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Two questions on OCamlDoc

[David Teller]

And while I'm asking complex questions, can anyone think of a way of
asking OCamlDoc to resolve [string] to [String.t], ['a list] to ['a
List.t], ['a array] to ['a Array.t], etc?

Thanks,
 David

On Tue, 2008-09-02 at 13:47 +0200, David Teller wrote:
> Hi everyone,
> 
>  I'm currently toying with OCamlDoc, with very little success. I'm
> attempting to do two things:
> * getting OCamlDoc to understand that some modules (which I can modify)
> contain the documentation for some other modules (which I can't) replace
> some modules with others
> * inlining the documentation for modules in modules which import those.
> 
> I need a little help.
> 
> Let me detail this.
> 
> *** Documentation replacement ***
> My project uses modules M_lib1, M_lib2... which come from a variety of
> libraries. For each of these modules, I have created  a module
> M_lib1_with_doc, M_lib2_with_doc, which imports the corresponding
> library module but tailors the documentation to my project. However, for
> technical reasons of mechanical generation, assuming that M_lib1 refers
> to M_lib2, M_lib1_with_doc still refers to M_lib2 instead of referring
> to M_lib2_with_doc. Consequently, when generating the documentation of
> M_lib1_with_doc, ocamldoc doesn't link the generated pages to the
> documentation of M_lib2_with_doc but rather attempts to link it to
> M_lib2 (and fails, as expected).
> 
> Now, I could rework the mechanical generation of my modules and in time,
> I will. However, for the moment, I'm looking for a purely OCamlDoc-based
> solution. I'd like to be able to ask OCamlDoc to please consider every
> reference to M_lib2 as actually meaning a reference to M_lib2_with_doc.
> 
> I have tried to override method [text#html_of_Ref], without much
> success. Is there a simple solution for this?
> 
> *** Inlining modules ***
> I have a few modules whose sole role is to include one or two existing
> modules. By default, when meeting [include], OCamlDoc, ocamldoc only
> generates a link from the container module to the inlined module. In
> this case, I'd rather want the whole documentation of each of these
> modules to be inlined.
> 
> Is that possible?
> 
> Thanks in advance,
>  David
> 
-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Another question on OcamlDoc

[Jan Kybic]

> And while I'm asking complex questions, can anyone think of a way of
> asking OCamlDoc to resolve [string] to [String.t], ['a list] to ['a
> List.t], ['a array] to ['a Array.t], etc?

Let me add another couple of questions about OcamlDoc. I am sorry if
this is a common knowledge.

   - how can I tell OcamlDoc to only process some files?
     Actually, the question is rather how to make OcamlDoc ignore the
     unresolved dependencies and "Unbound type constructor" errors.

     [Sometimes it is as if OcamlDoc and Ocaml did not parse the files
     in the same way - a program which compiles with ocamlopt gives me 
     "Unbound type constructor errors" with ocamldoc. I will try to
     reduce my code into a simple case to post it here later.]

   - how can I tell OcamlDoc to run a preprocessor on the file first?
     (I am using ocaml+twt)

Thanks,

Jan


-- 
-------------------------------------------------------------------------
Jan Kybic <kybic@fel.cvut.cz>                       tel. +420 2 2435 5721
http://cmp.felk.cvut.cz/~kybic                      ICQ 200569450

Re: [Caml-list] Another question on OcamlDoc

[David Teller]

According to the documentation, ocamlfind can manage that.

Cheers,
 David

On Tue, 2008-09-02 at 14:48 +0200, Jan Kybic wrote:
>    - how can I tell OcamlDoc to run a preprocessor on the file first?
>      (I am using ocaml+twt)

-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Another question on OcamlDoc

[Maxence Guesdon]

On Tue, 02 Sep 2008 14:48:50 +0200
Jan Kybic <kybic@fel.cvut.cz> wrote:

> > And while I'm asking complex questions, can anyone think of a way of
> > asking OCamlDoc to resolve [string] to [String.t], ['a list] to ['a
> > List.t], ['a array] to ['a Array.t], etc?
> 
> Let me add another couple of questions about OcamlDoc. I am sorry if
> this is a common knowledge.
> 
>    - how can I tell OcamlDoc to only process some files?
>      Actually, the question is rather how to make OcamlDoc ignore the
>      unresolved dependencies and "Unbound type constructor" errors.

Does it stop ocamldoc or does is end in elements not linked in the final
doc ?
If it stops ocamldoc, then this is a compilation problem. Make sure you
give the same options (-I, -rectypes, ...) to ocamldoc than to ocamlc.
In th second case, you can use the -hide-warnings option.
> 
>      [Sometimes it is as if OcamlDoc and Ocaml did not parse the files
>      in the same way - a program which compiles with ocamlopt gives me 
>      "Unbound type constructor errors" with ocamldoc. I will try to
>      reduce my code into a simple case to post it here later.]
> 
>    - how can I tell OcamlDoc to run a preprocessor on the file first?
>      (I am using ocaml+twt)

Use the -pp option of ocamldoc, which works the same way as for ocamlc.

Regards,

Maxence


-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/

Re: [Caml-list] Another question on OcamlDoc

[Jan Kybic]

>> Let me add another couple of questions about OcamlDoc. I am sorry if
>> this is a common knowledge.
>> 
>>    - how can I tell OcamlDoc to only process some files?
>>      Actually, the question is rather how to make OcamlDoc ignore the
>>      unresolved dependencies and "Unbound type constructor" errors.
>
> Does it stop ocamldoc or does is end in elements not linked in the final
> doc ?
> If it stops ocamldoc, then this is a compilation problem. Make sure you
> give the same options (-I, -rectypes, ...) to ocamldoc than to ocamlc.
> In th second case, you can use the -hide-warnings option.

I think I know what the problem was. I was compiling a program with
some of the source files in subdirectories, like

  ocalmfind ocamlc <some options> bootstrap/parallel.mli

Now when running ocamldoc like

  ocamlfind ocamldoc <some options> bootstrap/parallel.mli

it was capable of reading the source *.mli file but apparently it
also needs the *.cmi (or *.cmx ?) files which it could not find. So
the solution was to add the "include" option:

  ocamlfind ocamldoc <some options> -I bootstrap bootstrap/parallel.mli

So now everything is working well. Thank you for your help.

Jan 

P.S. I am using the source files from subdirectories as a means of
sharing a source code between projects. It works but it is kind of
fragile. Does anyone have a better method?



-- 
-------------------------------------------------------------------------
Jan Kybic <kybic@fel.cvut.cz>                       tel. +420 2 2435 5721
http://cmp.felk.cvut.cz/~kybic                      ICQ 200569450

Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon]

On Tue, 02 Sep 2008 14:05:31 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

> And while I'm asking complex questions, can anyone think of a way of
> asking OCamlDoc to resolve [string] to [String.t], ['a list] to ['a
> List.t], ['a array] to ['a Array.t], etc?

Maybe raw string substitution ?

Hacking in the internal representation of types to change their names way
work but it's currently out of my abilities.

Regards,

Maxence

-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/

Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon]

On Tue, 02 Sep 2008 13:47:08 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

>      Hi everyone,

Hello,

>  I'm currently toying with OCamlDoc, with very little success. I'm
> attempting to do two things:
> * getting OCamlDoc to understand that some modules (which I can modify)
> contain the documentation for some other modules (which I can't) replace
> some modules with others
> * inlining the documentation for modules in modules which import those.
> 
> I need a little help.
> 
> Let me detail this.
> 
> *** Documentation replacement ***
> My project uses modules M_lib1, M_lib2... which come from a variety of
> libraries. For each of these modules, I have created  a module
> M_lib1_with_doc, M_lib2_with_doc, which imports the corresponding
> library module but tailors the documentation to my project. However, for
> technical reasons of mechanical generation, assuming that M_lib1 refers
> to M_lib2, M_lib1_with_doc still refers to M_lib2 instead of referring
> to M_lib2_with_doc. Consequently, when generating the documentation of
> M_lib1_with_doc, ocamldoc doesn't link the generated pages to the
> documentation of M_lib2_with_doc but rather attempts to link it to
> M_lib2 (and fails, as expected).
> 
> Now, I could rework the mechanical generation of my modules and in time,
> I will. However, for the moment, I'm looking for a purely OCamlDoc-based
> solution. I'd like to be able to ask OCamlDoc to please consider every
> reference to M_lib2 as actually meaning a reference to M_lib2_with_doc.
> 
> I have tried to override method [text#html_of_Ref], without much
> success. Is there a simple solution for this?

A simple way (but not always possible, due to name clashes) would be to
use some script to perform string substitution in generated html files; in
your example, replacing all "M_lib2" by "M_lib2_with_doc". you could indeed
try to do this by overriding the method html_of_Ref. What problem do you
encounter ?

Another way would be to use some "cat" commands to create new
"..._with_doc.ml" files, compile them and use your "..._with_doc.mli" as
documented interface.

> *** Inlining modules ***
> I have a few modules whose sole role is to include one or two existing
> modules. By default, when meeting [include], OCamlDoc, ocamldoc only
> generates a link from the container module to the inlined module. In
> this case, I'd rather want the whole documentation of each of these
> modules to be inlined. 
>
> Is that possible?

May be. You could try to override the method html_of_module_element so that,
when you encounter a Element_included_module, you search the real module by
its name and print its elements instead of just "include ...".

Does this help ?

Regards,

Maxence


-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/

Re: [Caml-list] Two questions on OCamlDoc

[David Teller]

Okay, I've found the solution to most of my problems, thanks to Maxence.
The code will be committed soon to the Batteries repository if anyone is
interested.

I have one more question, though: assuming that I have a reference to a
[t_module] for a module with both a [.mli] and a [.ml], is there a
simple way to access the underlying implementation without having to
reparse [m_code]?

Thanks,
 David

On Tue, 2008-09-02 at 13:47 +0200, David Teller wrote:
> Hi everyone,
> 
>  I'm currently toying with OCamlDoc, with very little success. I'm
> attempting to do two things:
> * getting OCamlDoc to understand that some modules (which I can modify)
> contain the documentation for some other modules (which I can't) replace
> some modules with others
> * inlining the documentation for modules in modules which import those.

-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act
brings liquidations. 

Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon]

On Fri, 05 Sep 2008 12:25:03 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

> Okay, I've found the solution to most of my problems, thanks to Maxence.
> The code will be committed soon to the Batteries repository if anyone is
> interested.
> 
> I have one more question, though: assuming that I have a reference to a
> [t_module] for a module with both a [.mli] and a [.ml], is there a
> simple way to access the underlying implementation without having to
> reparse [m_code]?

What do you mean by access ? do you want a link to a html page of the code ?
And what do you mean by "reparse the [m_code]" ?

Regards,

Maxence

Re: [Caml-list] Two questions on OCamlDoc

[David Teller]

I'm doing some pre-treatment on the module structure before actually
generating documentation. In particular, I'd like to be able to find out
if the .ml contains an inclusion of some given module -- even if there
is a .mli -- as this will change the resulting structure.

Is there a way to do such a thing?

Thanks,
 David


On Fri, 2008-09-05 at 14:03 +0200, Maxence Guesdon wrote:
> What do you mean by access ? do you want a link to a html page of the code ?
> And what do you mean by "reparse the [m_code]" ?
> 
> Regards,
> 
> Maxence
> 
-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon]

On Fri, 05 Sep 2008 14:33:43 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

> I'm doing some pre-treatment on the module structure before actually
> generating documentation. In particular, I'd like to be able to find out
> if the .ml contains an inclusion of some given module -- even if there
> is a .mli -- as this will change the resulting structure.
> 
> Is there a way to do such a thing?

You may use ocamldoc on your .ml file and look if it contains a
Element_included_module refering to some given module.

Does it help ?

Regards,

Maxence

-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/

Re: [Caml-list] Two questions on OCamlDoc

[David Teller]

Let me rephrase: I'm doing that pre-treatment from inside ocamldoc.
Therefore, I don't think that running ocamldoc from ocamldoc is an
option. Now, perhaps I should try and access data visible to Odoc_cross
or Odoc_analyse?

Cheers,
 David


On Fri, 2008-09-05 at 14:37 +0200, Maxence Guesdon wrote:
> On Fri, 05 Sep 2008 14:33:43 +0200
> David Teller <David.Teller@univ-orleans.fr> wrote:
> 
> > I'm doing some pre-treatment on the module structure before actually
> > generating documentation. In particular, I'd like to be able to find out
> > if the .ml contains an inclusion of some given module -- even if there
> > is a .mli -- as this will change the resulting structure.
> > 
> > Is there a way to do such a thing?
> 
> You may use ocamldoc on your .ml file and look if it contains a
> Element_included_module refering to some given module.
> 
> Does it help ?
> 
> Regards,
> 
> Maxence
> 
-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon]

On Fri, 05 Sep 2008 14:42:53 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

> Let me rephrase: I'm doing that pre-treatment from inside ocamldoc.
> Therefore, I don't think that running ocamldoc from ocamldoc is an
> option. Now, perhaps I should try and access data visible to Odoc_cross
> or Odoc_analyse?

Indeed, the structure of the .ml file is lost after merging .ml and .mli.
You have to reanalyse the .ml.

Regards,

Maxence

-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/