Desired Behavior

Odoc has support for building documentation across multiple packages, but for this to work one needs to write a config file to tell Odoc which packages to load.

The format is fairly simple, the odoc-config.sexp file just needs to contain>

(packages foo bar baz)

The packages to reference are per-package thus can be read from the depends field of the package stanza in dune-project, by filtering which OPAM packages are marked with :with-doc filter.

When generating OPAM files, these documentation dependencies should translate into with-doc & post dependencies.

Example

(package
  (name yojson-five)
  (synopsis "Yojson-five is a parsing and printing library for the JSON5 format")
  (description "Yojson-five is a parsing and printing library for the JSON5 format.
It supports parsing JSON5 to Yojson.Basic.t and Yojson.Safe.t types.")
  (documentation "https://ocaml.org/p/yojson-five/latest")
  (depends
    (ocaml (>= 4.08))
    (sedlex (>= 2.5))
    (yojson (= :version))
    (mdx :with-doc)
    (odoc :with-doc)
    (alcotest (and :with-test (>= 0.8.5)))))

creates an odoc-config.sexp with

(packages mdx odoc)

And the generated OPAM file would look like this:

depends: [
  ...
  "odoc" {with-test & post}
  "mdx" {with-test & post}
  ...
]