Odoc link to source code

Learning
1

I’m using default dune build @doc, and would like to add links to source files in generated doc’ion. One of the top-level features of odoc, as listed here, is “Link to Source Code”, so maybe I’m doing something wrong.

I have interfaces (and all doc strings) in mylib.mli, with function impl’ns and def’ns of types t etc. in mylib.ml

What I’d really like is to be able link to the .ml def’ns of types, even though they are hidden from the API (e.g. type t in API / .mli, but type t = A | B | C in .ml)

Thanks.

1 Like
2

dune doesn’t support the newer features of Odoc yet and will not generate the source code pages.

We are building a driver for Odoc that is simpler than Dune for testing purposes and for integrating the features into ocaml.org. Beware that this is actively being worked on and that it is not stable at all. You should not expect it to work but if do use it, we’d be glad to ear your feedback.
If you want to try it, pin the package odoc-driver from git+https://github.com/ocaml/odoc#master and run it like this:

odoc_driver opam -p my_pkg
4 Likes
3

Wonderful! I had to install odoc-md first before odoc-driver (missing dep?), and run odoc_driver dune to produce documentation for my package with links to the source code _o/ It looks fantastic!

A few comments since this is still in development… The links to packages in the root index.html were not correct? The _build/default/src/ is a bit verbose in the url, any way to shorten it? (the html files are referring to css/js at ../../../ so I guess not?)

2 Likes
4

Thanks for sharing! That looks like a bug indeed.

Using the opam mode might work better, even for local dune packages:

dune build -p my_package
dune exec -- odoc_driver opam -p my_package

If it doesn’t, try pinning and installing your packages in an opam switch.

2 Likes