odoc icon indicating copy to clipboard operation
odoc copied to clipboard

Driver: Read a config file to apply the right `-P` and `-L`.

Open panglesd opened this issue 5 months ago • 0 comments

This PR makes the driver follow a convention to know which packages/libraries to include in -P/-L during linking, for opam-installed libraries. (This convention is what I understood that we proposed in various dev meetings. However, I have a slightly different proposition, see at the end of the post).

The file has to be at path <opam_root>/doc/<pkgname>/odoc-config.sexp.

It has to be a valid sequence of whitespace-separated s-expression. Each s-expression must be of the form '(libraries <atom list>) or (packages <atom list>). The atoms present in each field correspond respectively to the -L and -P to add to the linking of the pages and modules of the package. That is, atoms in 'library must be library names, while atoms in packages must be package names.

I tried to add cram tests for the driver, but failed miserably. I thus included instructions on how to run tests.


I think specifying pages at a package level, and libraries at a library level, is confusing for the user and does not add much value. I would propose to have a single (deps <package list>) stanza which adds:

  • a -P for each package listed
  • a -L for each library of each package listed

This is less "fine-grained" but less confusing I think. Let me know if there is some advantages to being able to specify dependencies at the library granularity!

panglesd avatar Sep 10 '24 11:09 panglesd