I don’t really know what that question means.
Before odoc 2.0.0 .mld are attached to the root of packages in a flat name space. There’s no problem in organising your sources into directories as long as names don’t clash (it’s possible that odig will not look recursively into look into $(opam var $PKG:etc)/odoc-pages but that’s easy to change).
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 .mld files self-describing about their attachement.
That’s the idea behind extraction. Suppose each of your .mld fully describes self-contained example like in @antron’s tutorial sections. Basically the sequence of code fences and verbatim fences interleaved by explanations define the contents of (relative) filepaths.
Explanations…
{ hello.ml | … |}
Explanations…
{ hello.ml | … |}
Explanations…
{ dune | (executable … |}
Now you have your tutorials fully rendered and integrated in your odoc docset and you can instruct your users to:
opam install dream
odoc extract -d hello $(opam var dream:etc)/odoc-pages/tutorials/hello.mld
cd hello && dune build
To play with the sources.
Your build system can also do that extraction and test it builds and runs as you wish – ensuring the overall quality of said tutorials. (You could also imagine having the extraction as promotion cycle in your repo).
Here again we have the nice property of bringing the tutorial publication costs for programmers down to zero, with checked crosslinks between APIs, docs and other packages, all that with a good story about verifying their sources are up-to-date.
For users of said tutorials they get a predictable place to find all this rendered either online or locally as well as a simple, uniform, procedure to play with them (see the steps above).
Just with the documentation tool of the language, by simply writing .mld files, we liberated programmers to have to devise their own system for that and ensured a consistent end-user experience for this across packages.