Dune should write and install `odoc-config.sexp` files

[Leonidas-from-XIV]

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}
  ...
]

[Leonidas-from-XIV]

@jonludlam Can you confirm that this would be what we need to resolve #11716? Unlike that PR I don't think we need to add any additional fields to dune-project as we have all the required information already (or well, established ways to add it).

[jonludlam]

I think we should only put on post if required - can you do something like (odoc :with-test :post)?

[Leonidas-from-XIV]

@jonludlam Sounds like a good idea, but how should we determine whether post is required?

[Leonidas-from-XIV]

Alternatively we can also require that both :with-doc and :post are set, maybe that's an alternative?

[rgrinberg]

As mentioned in the PR, guarding the generation of this config file based on the detection of package dependencies is suspect. If generating the file requires no additional dependencies, then we should always do it.