IIUC in odoc 2.0.0 it should be possible to attach .mld files anywhere in your docset – though I’m personally not really happy that they did not mandate a convention on how to do that or made
.mldfiles self-describing about their attachement.
To address this point specifically, in odoc 2.0.0 there is support for the driver of odoc, that is, odig, dune, digodoc, voodoo and so on, to decide the hierarchy in which the resulting files are written. So it can choose to put each mld file in the same directory, the index in one and the rest in another, or any other scheme it chooses. The same goes for the top-level modules (sub modules, module types and similar will all be put in a subdirectory of the top-level module in which they’re found).
We will be able to use the same underlying mechanism to allow the package authors to specify a hierarchy of output files too, but there’s some more work required before this is a useful feature - and some work to decide exactly how this hierarchy should be specified. This may well end up being some sort of self-describing annotations in the mld files themselves. I would very much welcome input on these – from document authors as well as driver maintainers – as they need to be thought through carefully before we start making recommendations to the community.
Secondly, @dbuenzli’s description of extraction is spot on, with one minor alteration. Our current plan is that mdx will do the extraction and testing, as that is mdx’s primary function, whilst odoc’s primary job is generating documentation. All we need to do is specify the concrete syntax to pass the metadata (see the meeting minutes here), and then it should be a relatively simple job to teach mdx how to handle mld files.