search

ocamllabs / opam-doc

Produce documentation for libraries installed with OPAM
22 stars 9 forks source link

Help required with running opam-doc #1

Closed heidihoward closed 10 years ago

heidihoward commented 11 years ago

I'm trying to run opam-doc on core

So far I've:

(1) Generating .cmt[i] amd .cmd[i] files

(2). Generating the HTML

But i just can't see produce any actual docs. The best I can get a index.html with gibberish like "„•¦¾,³› ÐÐÐÐ@ %Clock0Ü;S´¦{¸ö+°M—?³ù 'mir-doc@A 'Console0¾‡„f¦°H‡»K"

Can you tell me exactly what to arguments to opam-doc and where to find the resulting html ?

vincent-botbol commented 11 years ago

Hi,

You actually need to generate the cmt files with 4.01.0dev+trunk as the typed tree slightly changed.

There is a simple method used in the 4.00.1+bin-doc compiler which is to replace the binaries with a script before calling the real compiler :

#!/bin/bash
which bin-doc &> /dev/null && bin-doc "$@" > /dev/null
ocamlc.real -bin-annot "$@"

Then, reinstall core and you should be set.

I usually tend to use : opam-doc -p core $(find <core_path>/ -name *.cm[dt]*)

In any case, the program should return an error telling the the cmt version handed is wrong. I'll get this fixed as soon as I can.

Thank you for noticing this.

samoht commented 11 years ago

Instead of that patch I think we can use the new OCAMLPARAM option. If you have some issues with it, please report on http://caml.inria.fr/mantis/view.php?id=6076 (would be nice to check that this option works as expected before the release of 4.01 though).

samoht commented 11 years ago

(and if it works we could add that option by default to the compiler description for 4.01)

lpw25 commented 11 years ago

OCAMLPARAM only takes care of adding the "-bin-annot" argument, we also need to run the "bin-doc" command with the same arguments as the compiler.

I hope to add a "-bin-doc" option to the compiler to replace the "bin-doc" command. Once that is done then OCAMLPARAM should be sufficient.

avsm commented 11 years ago

OCAMLPARAM, not OPAMPARAM

-a

On 13 Aug 2013, at 15:47, Thomas Gazagnaire notifications@github.com wrote:

Instead of that patch I think we can use the new OPAMPARAM option. If you have some issues with it, please report on http://caml.inria.fr/mantis/view.php?id=6076 (would be nice to check that this option works as expected before the release of 4.01 though).

— Reply to this email directly or view it on GitHub.

heidihoward commented 11 years ago

Thanks for the feedback

To separate the two issue, I've tried using the pre generated .cm[dt] files in opam-doc/cmt_folder-4.01.0dev+trunk/core_bench.109.34.00 and I'll still not sure if the html is being generated, if I do the following:

Then a empty directory called core_bench and a file called opam-doc.idx is created in my working directory, but where are the html files ?

If i add -index ./index.html to the call to oapm-doc, then a index.html is generated containing:

<84><95>¦¾^@^@^@6^@^@^@ ^@^@^@#^@^@^@^_ Ð@ *Bench_main0VÕ^E&e_Õ^Z-q®Ê/.^X^F *core_bench^D^D@A  ^D^C@@

heidihoward commented 11 years ago

@vincent-botbol

Am i right to assume that when you said

touch ocaml put this script inside the newly created ocaml file

you mean ocamlc instead of ocaml ?

heidihoward commented 11 years ago

Regarding generating cmt files with 4.01.0dev+trun.

@vincent-botbol I've followed the your steps (for cstruct), where can i now find the cm[dt]* files ?

There not in:

heidihoward commented 11 years ago

With some help from @lpw25, We have now generated some docs using opam-doc. For future reference, here are the issues and the solutions:

Problem: I couldn't generate docs from cmt(i) files in opam-doc/cmt_folder-4.01.0dev+trunk Solution: opam-doc can't generate docs from only cmt(i), it needs the cmd(i) too

Problem: After following @vincent-botbol instruction, I couldn't find the cm[dt]* files Solution: You need to repeat vincent's instruction for ocamlc.opt, ocamlopt.opt and ocamlopt. as well as ocamlc. The ~/.opam/4.01.0dev+trunk/build//_build/src/

Problem: After generating the HTML, the JavaScript wasn't working in when viewed in a browser Solution: Make sure that you start at the index.html in the current directory (not the index.html in the new subdirectory called ) and open docs in firefox instead of chrome, as chrome has an issue with AJAX requests from local directories

avsm commented 11 years ago

Here's my integration of all this into OPAM:

opam remote add opamdoc git://github.com/avsm/opamdoc-dev
opam switch 4.01.0beta1+opamdoc
eval `opam config env`
opam install opamdoc
opamdoc-rebuild
opamdoc-generate
open ~/.opam/4.01.0beta1+opamdoc/opamhtml/index.html
dbuenzli commented 11 years ago

What are the instructions for packagers ? Does this mean that packages themselves should generate and install cmti for each corresponding installed mli file ?

(one small annoyance if you use ocamlbuild is that this makes all your package dependent on 4.01.0 as it's the version that introduces the bin_annot tag to generate cmti files).

avsm commented 11 years ago

There are no instructions for packagers yet. This is still experimental and gathers up cmt files that are installed via an augmented ocamlc driver.

samoht commented 10 years ago

I think this is fixed now.