Hello hello,
I’m currently working on a project where I’d like to have a nice website explaining how to work with the code. Supposedly, I’d generate this with some documentation/static site generator. However, if possible, I’d like to be able to link to the odoc-generated documentation.
Does anyone have a workflow to do this nicely? Ideally I’d like to write documentation and tutorials using markdown or anything similar.
Cheers!
It’s a bit unclear what you mean by “project”.
But if that’s documentation for an OCaml library then I suggest not to make your own website (that is if you have a website have the docs there as a mirror of an odoc docset).
Users working with your library are unlikely to want to peruse and bookmark yet another website, with yet another stylesheet. They either want to read it on ocaml.org with all the other libraries they already use or locally on their computer once they have installed the library (e.g. with odig). That includes your library’s tutorials of course.
You can just use .mld pages for that, it’s not commonmark but you get checked cross-references into your API. See the odoc docs.
So, I definitely intend to document my library properly, but supposedly the website will be an entry point to “more”, e.g. potential blog posts, full-on tutorials etc.
I’d like everything to be joined under a single URL, even though the odoc subset will be available through odig/ocaml.org
Plus, to be fair, I do find mld to be somewhat clunky 
Though admitedly, documentations for your packages on erratique.ch are gorgeous
What exactly do you mean by that :–) ?
They keep on improving. You can now have media assets, tables, maths, etc. You can extract code out of them. Language wise they are full on par with what markdown plus extension would provide. And most of these markdown systems miss a crucial feature needed for documentation maintenance: checked cross-references, both between your .mld pages and in your API reference (don’t underestimate how important that is).
If it’s the default stylesheet that puts you off just make your own (I do). Also that doesn’t seem to be your case but if you don’t have the time so setup a website they make the path to publication exceptionally easy (publish your package on opam, they will be on ocaml.org).
I reworked the cmdliner docs recently which have all of what you mention except for blog posts.
The thing is that you need to put yourself in the shoes of your users. They are unlikely to use only your library but a couple of them, it’s a pain if each of these has its own home and way of presenting the documentation.
For myself I’d also be particulary annoyed if a library doesn’t allow me to work offline. Just for example this spring we had exceptional snow falls in my area, that meant no cellular network for one day, no electricity for two and road cut for three. These are perfect time to focus :–) And the meteorologists tells us these extreme events are not getting any rarer (in fact in a nearby valley, a village just got wiped off the map in a torrent of ice and mud 
).
So keep the offline documentation experience living!
Unfortunately not everything we want to talk about in the tutorials is OCaml-based. We’re building tooling for C and Rust programmers (possibly more in the future).
While the core library itself can be documented in mld, the rest is going to come in as painful quite quickly. Plus I don’t expect rust people to open OCaml.org to understand how to use a tool
Ah then I agree that .mld may not be your thing here (though you can certainly convince it to generate full websites). That’s what I meant by:
Unfortunately, Odoc doesn’t seem to be designed to include documentation on a website. It’s very difficult to customise the style or add your own menu. It’s also not easy to write the full user guide (unless you have very limited needs). I don’t think there is a good solution. Html_of_wiki is meant to solve this, but it needs to be updated and it’s not actively maintained as far as I can see.
I never tried it but I think that odoc html-generate --as-json doesn’t make it too hard for a processor to pickup the markup and wrap it with your website template.
I did write full user guides in the past and saw its limitation, but note that with the new parent child structure of odoc 3 this could be alleviated (didn’t try yet though). But you may have to get your hands dirty with running odoc yourself.
Yes I meant a real customisation very well integrated into the web site structure and with all the style customisation you would expect (say: put a class where you need it)
Please do open an issue on github with some more detail. While I can’t promise we’ll be able to make it work the way you want, the chances of a happy outcome are much higher if I know what you need 
The main issue is that I’m not 100% sure of what I’m looking for. Ideally, something as beautiful, expressive, and easy to write as e.g. docusaurus, but that can embed normal odoc pages?
Also, possibly, some literate programming features for tutorial?
I think we settled on docusaurus for now hosting with myorg.github.io, and each repo will have its own API documentation using myorg.github.io/repo, will create issues if any idea on how to make this more uniform arises
I had similar desires towards ocaml documentation and added markdown support on odoc, mostly to use the generated markdown in any static site generation that’s designed for docs with other pages, full customisation of styles and document content and add other pages.
It’s currently supported in odoc, and I plan to add support in dune very soon.
The biggest use-case would be melange.re documentation itself, but also, styled-ppx and reason-react.
I had similar desires towards ocaml documentation too.
For the literate programming features for tutorial I currently use mdx, and package it into a docusaurus site. For example here. The odoc is included in the sites as static pages, so they are not integrated and not referenced by the search. For example here.
I had tried in the past to reduce that use case down to a template and explained the challenges that surfaced. I then lost interest when I couldn’t make the json output really work for me (sorry!).
The markdown generation output, with dune support sounds great. Count me into your potential early adopters! My impression is that this is going to unblock what I was trying to get to. Thanks!
That actually would be great!
This is quite helpful actually! Thank you
I have limited time, but I plan to spend some time writing documentation and tutorials. I’ll first write a “non-automated” version, and then will try to understand what automations would be nice to have and provide feedback to the community
Do note that the markdown output has a rather important drawback - the links in the definitions of types and values aren’t present. For example, in the Lwt docs, the output for bind looks like:
whereas in the HTML docs, the types t in val bind are links to the definition of Lwt.t .
If you do end up trying it out though, please do let us know how you get on and report and problems on the issue tracker!
This could have been output with an html block.
yeah, the current mode is just exclusively markdown. I can see adding options to it to enable other html-enhanced elements.
If we render html in the markdown mode, this output can’t be used for github renderer, static site generators or problems with LLMs.
I’ll be sure to ping you on Slack when I have something to test. Thanks
These all look like pretty bad arguments to degrade the user experience. I’m not sure why you’d want to please the github renderer. If your static site generator is not able to render raw HTML in commonmark then maybe switch to another one. And for LLMs… ah yes, people never learn.
This seems to match my favorite workflow, which is to consume documentations locally. I don’t mean to convey that I have one and only one way of referring to the docs, but generally if I am being perfectly honest, my best source are to open the mlis in my editor directly, which I read as a trusted source of truth. Granted, I may be missing out on a whole spectrum of rendering niceties, but I tend to be distracted and my flow tends to break if I have to switch to looking at a doc in a browser or another external tool. Quite possibly, this is also inherited from many years of OCaml throughout ages where doc tools were not where they are today.
Under that perspective, a whole bunch of parameters are tilted. For example, a doc filled with odoc escape codes goodies that renders beautifully on ocaml.org is not the most readable when consumed from the mli. Also, a doc that has so many comments that you can’t fill the entire mli in your head on a reasonable screen tends to lower my UX. Because I like this workflow, and because I feel some reluctance to depend too strongly on odoc, I tend to favor (authoring and reading) pretty plain mlis comments. That’s my reasoning, and maybe can explain some of the divergence in preferences?
