Hello.
I am trying to use odoc for the Ocsigen documentation and I would love your advice on the right approach. To build the docs I wrote wodoc, a small layer that assembles and themes the output, and underneath it I rely on odoc_driver. I use odoc_driver because it documents a whole opam package together with its dependencies and handles the compile and link ordering for me, which I did not want to reimplement.
I hit a problem with Eliom. The package has two libraries, eliom.client and eliom.server, that expose modules with the same names on purpose: the client/server symmetry is central to the framework, so they cannot be given different names. When both libraries are on the link path, references in the client documentation resolve to the server's modules. For example the client's Content.Html ends up showing the server's definitions.
For now I work around it with a patched fork of odoc that links each unit only against its own library and its declared dependencies, so the two siblings are never on the same path (the patch is here ). It produces correct output for Eliom, but I realize this removes the package-wide reference availability that odoc_driver provides on purpose (so that any module of a package can be referenced from anywhere). So it is a regression for other packages and I do not think it belongs upstream as is.
I would like to discuss the cleanest way to handle this. From my investigation the wrong resolution seems to have two parts: same-named modules being picked by first-found order during link, and canonical paths that end up pointing to the sibling library. I am very happy to share a detailed reproduction and my findings if that helps.
Thanks for any guidance.
Hello.
I am trying to use odoc for the Ocsigen documentation and I would love your advice on the right approach. To build the docs I wrote wodoc, a small layer that assembles and themes the output, and underneath it I rely on odoc_driver. I use odoc_driver because it documents a whole opam package together with its dependencies and handles the compile and link ordering for me, which I did not want to reimplement.
I hit a problem with Eliom. The package has two libraries, eliom.client and eliom.server, that expose modules with the same names on purpose: the client/server symmetry is central to the framework, so they cannot be given different names. When both libraries are on the link path, references in the client documentation resolve to the server's modules. For example the client's Content.Html ends up showing the server's definitions.
For now I work around it with a patched fork of odoc that links each unit only against its own library and its declared dependencies, so the two siblings are never on the same path (the patch is here ). It produces correct output for Eliom, but I realize this removes the package-wide reference availability that odoc_driver provides on purpose (so that any module of a package can be referenced from anywhere). So it is a regression for other packages and I do not think it belongs upstream as is.
I would like to discuss the cleanest way to handle this. From my investigation the wrong resolution seems to have two parts: same-named modules being picked by first-found order during link, and canonical paths that end up pointing to the sibling library. I am very happy to share a detailed reproduction and my findings if that helps.
Thanks for any guidance.