Can you have multiple .mld files per folder level? And can .mld files contain code snippets that are typechecked and compiled like regular OCaml code? The big advantage of .ml files is that thy (obviously) support that.
In fact if you look at it from a certain angle, .ml file format is a surprisingly appropriate document authoring format. Just attach the (** to the top of the file (module), and you’re good to go.
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.
Hi - I’m the author of Diátaxis. This month and next I’ll be doing some documentation workshops for open-source projects. If that’s of interest, please let me know.
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.
This is really nice. Consider moving the examples into their own repos and making them “template” repos, or adding them as templates to drom.
I don’t understand this choice. mdx seems to be an entirely different idea and project with an alternate markup. It doesn’t make sense to me. This functionality should be simply integrated in odoc.
Thanks. I will indeed move a few of the examples out into template repos, in particular probably Hello, world! and the full-stack examples. But with the large number of examples, it is probably impractical to move them all out and maintain the setup. I am happy to link to drom templates if someone creates them and notifies me.
Your confusion is understandable, but due to the history of how mdx evolved. Most of the complexity within the mdx tool is to handle the OCaml code extraction/evaluation/promotion, and the remainder is the markdown parsing and extraction from surrounding syntax. The rough plan is to extract out the OCaml-specific bits from mdx into a separate library that does just the OCaml fragment processing, and then have mdx and odoc use that. @jonludlam and the mdx maintainers are discussing the best way to do this at the moment.
There won’t be any markdown-specific tools in odoc itself. Once the dust has settled on the end-to-end authoring story for odoc, I expect that we’ll see some tools to transcode the authoring format into something like Markdown. I’m more interested in getting LSP support and auto-completion for the ocamldoc format first though, since it is a far less ambiguous authoring syntax than Markdown is.
Somewhat off-topic, but just wanted to mention alectryon https://github.com/cpitclaudel/alectryon, a documentation system for Coq, which I think has an interesting approach. The basic idea is to lift the writing of documentation to the same level as code: you can either write a Coq file with embedded documentation which you can then extract into a reST document (or webpage, etc), or write a reST document with “Coq comments” which can then be extracted into a Coq source file. Of course, the goals of that project are not the same as those of odoc relative to OCaml, but it seems interesting nonetheless. See also the blog post https://plv.csail.mit.edu/blog/alectryon.html if you are interested.
Cheers,
Nicolás
Well the confusion is that mdx has nothing to do with odoc… I think you always tend to make things much more complicated than they could be. Start by providing basic tools that work well, it’s more important to have something than nothing. @rizo’s proposal with a bit of more work is entirely enough.
And I insist that from a basic user experience point of view this should be fully integrated in odoc and not made a seperate tool. People should learn to write:
odoc extract -d hello $(opam var dream:etc)/odoc-pages/tutorials/hello.mld
and not
opam install random-other-tool-to-extract
random-other-tool-extract -d hello $(opam var dream:etc)/odoc-pages/tutorials/hello.mld
because odoc is simply the tool that handles .mld files.
I do not have any context on the mdx integration requirements, but I’m happy to revive my PR if it is still useful.
mdx is already a basic tool that works well, and is precisely complicated enough to write a book with. We wrote the whole of Real World OCaml using it: book/book at master · realworldocaml/book · GitHub.
Go right ahead and discuss your specific proposal with @jonludlam and the odoc maintenance team if you think it’s a better approach.
So in OCaml terms this would be writing an .ml file with embedded documentation in it that odoc would extract to HTML, I guess.