alan-turing-institute / whatwhat

A reimagining of nowwhat in OCaml
MIT License
0 stars 0 forks source link

Fix warnings in `dune build @doc` #64

Closed triangle-man closed 1 year ago

triangle-man commented 1 year ago

For example:

> dune build @doc

File "../../lib/.Whatwhat.objs/byte/whatwhat.odoc":
Warning: Failed to lookup type unresolvedroot(Stdlib__Map).Make(unresolvedroot(Stdlib).Int).t Parent_module: Unresolved apply
yongrenjie commented 1 year ago

This is an upstream issue which has to do with dune not being able to access other packages installed in the current switch, meaning that it can't access or cross-reference the docs of any dependencies (not even stdlib): https://github.com/ocaml/odoc/issues/794

The workaround I found (discussed here) was to not use dune build @doc but rather odig. On the first time, do:

opam install odig

# install the package into the current opam switch
cd whatwhat
dune build
dune build @install
dune install

# generate and view documentation
odig doc whatwhat

To subsequently update the docs:

dune build
dune install
odig doc -u whatwhat   # (update)

That runs without errors (if you use odig doc -v whatwhat it spews a load of warnings from the dependencies, but none from whatwhat itself).

I'll add this to the readme or wiki. Added to readme (in d7a777e) and wiki