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.

2 Likes
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
5 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
5

Feedback? It is great! I’ve been able to use odoc_driver opam with the JSON output to embed OCaml API documentation into my site while maintaining the look and feel. Examples:

The only things I had to (or still have to) work around are:

  • The TOC for ocaml-base-compiler is huge. See the sidebar for Stdlib.Format on my site. I can post-process the TOC, although post-processing would be easier if the metadata JSON fields were pure JSON rather than HTML.
  • Because odoc_driver reads .cmt files it must be built for the same version of OCaml as the documentation being generated. The practical implementation is that odoc_driver can’t generate ocaml-base-compiler documentation for versions less than its minimum (ocaml (>= 5.2)) requirement. This is minor for me, but probably not for the main ocaml.org site.
  • I can’t run odoc_driver on Windows because of its eio dependency.

Thanks odoc team!!

EDIT: In hindsight I should have made this post in a new topic.

2 Likes
6

That’s awesome!

The TOC for ocaml-base-compiler is huge.

Thanks for the feedback! We’ll look into it. It has been a challenge to build documentation for ocaml-base-compiler so far.

Because odoc_driver reads .cmt files it must be built for the same version of OCaml as the documentation being generated.

That’s the case for odoc but not for odoc_driver. You can build odoc_driver with a 5.2 compiler and use it to drive odoc built with a different compiler (which supports down to 4.02).

I can’t run odoc_driver on Windows because of its eio dependency.

The driver is still work in progress and Windows wasn’t one of our usecase yet. We’ll definitely want to support Windows later, if the driver continues to be useful.

1 Like
7

Happily, in the beta release of odoc_driver we’ve removed the global_toc field from the generated json in favour of a sidebar.json file in the package root. This one is pure data, not HTML :slight_smile:

1 Like