The state of Ocamldoc and Odoc

Community
21

This is what I want. I’ve been discussing/planning this on and off, but I don’t have time to implement it right now.

22

TBH I don’t think that’s easily achievable. Take for example the title splicing that occurs when your refer to the id of the section of another package via the {!pkg.M.secid} directive.

Also while nowadays it is easy to do an odig online-doc PKG to get to the particular docs a package PKG may publish online I think there’s more value in having a docs.ocaml.org in the vein of docs.mirage.org that centralizes the docs of packages published on the opam repo (for discussing online) and the odig approach that makes you a local doc set for the packages you have installed and are presumably interested in.

Would docs.ocaml.org exist I wouldn’t mind no longer publishing API docs on my website and relagating that to the packaging infrastructure.

1 Like
23

Ah that makes sense too. I view that as a second, more complex step after we get a central docs.ocaml.org working. The reason is package versions: odoc needs a consistent view of the dependencies (just like the normal OCaml compiler cannot mix and match compiled interfaces). Everyone who is publishing docs will need to agree on their dependency chain versions and ensure they are exactly the same. This is possibly solvable in odoc, but it seems like a complex new feature, and so I’d rather focus on publishing the centralised documentation first.

24

I’d rather focus on publishing the centralised documentation first.

Do we have any concrete plans for this yet? I know that everyone who knows the ins and outs of CI and consistent package universes is very busy, but maybe if we had a clear picture of what was needed we could get some help from the community. Or is it mostly about setting up the necessary hardware?

25

Quick question,
How can I “compile” a complete package using odoc ?
For example, for olmi I’m trying to run : odoc compile _build/lib/olmi.cmt, but I have to build all of the internal modules of the package, and odoc could not generate an index for the package.

Edit : What I understand is that it requires an .mld file, But after some searches, I can not find the form of the .mld file: /, I naively tried:

odoc-v1.1.1
Olmi
OlmiInterfaces
OlmiMake
26

That may be a little bit long to answer is certainly still in flux. You may want to try to follow this function which is the way odig does it.

1 Like
27

Ah sorry I missed your edit. An .mld file is a file that contains ocamldoc text (whithout the OCaml surrounding comments). Notably you can use {!module: M1 M2} in there to list your modules. See for example how odig generates them.

1 Like
28

Also note that {!indexlist} is not yet supported by odoc.

2 Likes
29

Thanks a lot ! It is excactly what I need !

Edit : Hum, I’m not very shrewd, but with this file :

odoc-v1.1.1

{!modules: Olmi OlmiInterfaces OlmiMake}

I get : Error while unmarshalling "lib/olmi.mld": input_value: bad object

30

Please show your invocation of odoc but I suspect you cannot specify .mld files as positional arguments those are supposed to be .odoc objects.

IIRC you have to specify it through the --index option, have a look at what odig does in the functions I mentionned or lookup odoc html --help and complain loudly on odoc's tracker if there’s anything that is unclear there.

31

Are there any guides on how to setup your (jbuilder) project so that odoc can process its documentation? What I’ve tried:

  1. odig odoc mylib: this does not generate my docs, as odig doc mylib only shows the index page with only package name and info.

  2. jbuilder build @doc (following this guide) does nothing, which I think is expected since I don’t have any doc alias on my jbuild and have no idea what to put in it (github search on doc filename:jbuild is not giving me answers)

  3. topkg doc complains that I have no pkg/pkg.ml, I think I need topkg-jbuilder but I suppose it will take me back to point 2.

FWIW this is the project that I’m trying it on, I’m trying to generate docs for the stuff in lib. Help really appreciated!

32

Your installed package needs to follow the odig conventions for odig to be able to its job see odig help packaging.

33

Thank you @dbuenzli, but I’m afraid I’m missing some context of the explanation. I understand so far about the LIBDIR and DOCDIR. What I’m confused is this bit:

OCAML API RECOGNITION
       The OCaml API of a package PKG is defined by all the compiled module
       interfaces (cmi) files that are present in the path hierarchy rooted at
       LIBDIR/PKG.

Perhaps my question is how to get the cmis there, as my LIBDIR/mylib only contains META, opam, and opam.config. I’ve pinned and installed my lib from local directory using the normal workflow, but somehow there are no build artifacts there… I realize this is not the concern of odig though, but I could use some example.

Oh, as I was writing this I think perhaps there’s something wrong on my mylib.install file. Let me check that in the mean time.

34

I don’t know exactly how jbuilder works but I suspect you need to add something like a public-name here so that your library gets installed, some jbuilder user may confirm. If ls $(opam config var lib:mylib) doesn’t have your library build artefacts odig won’t be able to do anything.

1 Like
35

Yes, I came to that conclusion too, going to try it later tonight. Thanks again for your help!

36

After this commit, both odig odoc and jbuilder build @doc works! :tada: Learned something new today.

4 Likes