Documentation created by dune build @doc looks ugly

I’m trying to get documentation comments converted to HTML pages. Following the documentation of Dune on that matter, I simply install the odoc package and run dune build @doc. (Assuming that my library is public.)

I wrote the following library (mylib with a module Mylib):

(** Demo library *)

(** Increase number
    @param x Number to increase
    @returns Number [x] increased by one
*)
let inc x = x + 1

But the documentation in _build/default/_doc/_html/mylib/Mylib/index.html looks ugly when I open it with a webbrowser:

The headings “Parameter” and “Returns” aren’t even bold or somehow different from the remaining text content. Is this the default style, or did I do something wrong? Can I change this?

I noticed that the link in Dune’s documentation regarding the formatting rules refers to the OCaml manual (here), which seems to use ocamldoc (and not odoc).

I’m confused. Do I use odoc or ocamldoc when I write dune build @doc?

Are the @params and @returns annotations deprecated perhaps? The standard library API documentation doesn’t seem to have dedicated sections for arguments and/or return values.

8 posts - 5 participants

Read full topic