odoc
odoc copied to clipboard
Driver: Read a config file to apply the right `-P` and `-L`.
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!