By the way, this is relevant. http://bettermotherfuckingwebsite.com/
It’s remarkable how much more readable things get with a few small changes to the CSS of a site.
Definitely the line length is something that is not something the OCaml world cares a lot about 
And in the same time it’s really, really easy to fix
I might be misunderstanding you here, but line length is well-preserved in odoc-generated pages (around 80 characters). However, it indeed can use a little bump on text size in my opinion.
I was talking about most of the classic manuals on INRIA websites etc.
As was I. The main OCaml manual has quite long lines. I don’t know that much about what odoc does yet, though for HTML, this is mostly controlled by the CSS in use.
By the way, there was a pull this morning to tweak the CSS for the 4.07 version of the manual. It only adjusts the interline spacing and the line width and centering, but it already looks substantially better. (It’s literally only a couple of lines changed.)
I’m new in the OCaml community and curious if reStructuredText together with Sphinx ever was considered? There is a free hosted version called Read the Docs that you’ve most likely heard of. One reason to use a pre-existing solution would be that knowledge of reStructuredText would be transferable to other projects.
People more vested than me have written some interesting blog posts:
2 Likes
The Coq project has also adopted rST/Sphinx. I’m more agnostic on the particular choice of tools, somewhat more interested in seeing people take more time and effort writing documentation itself.
1 Like
odoc is the hot new tool for OCaml documentation. While a lot of effort has been put into supporting html, I personally wouldn’t mind just creating rst output instead and letting other people keep up with the latest css styles.
It seems @jacquev6 has already implemented a Sphinx domain for OCaml. Maybe that could be useful?
1 Like
I have indeed. I used it to document ocaml-hashid if you want to have a look. This is a very short doc but I find it satisfying and the domain can do much more.
I also tried to implement an autodoc-like Sphinx directive (to extract doc from the code during the Sphinx build instead of generating .rst files beforehand), in the same project, but it is highly experimental. I would gladly hand it over to someone who know the OCaml compiler internals better than me.
2 Likes
I can see how this could be useful. What might be challenging is supporting cross-referencing in the same way odoc currently does. But I like the idea of delegating this work to existing tools. In particular GitHub already know how to render it.
On the other hand I would actually like to consider reStructuredText as an alternative to ocamldoc in the future. It’s more flexible than markdown and can be easily extended.
2 Likes
I would really like people to actually start writing documentation rather than endlessly ponder what will be the next half-broken solution to this supposedly problem.
The tools might not be perfect but they have been here and improving for as a long as I started publishing free software OCaml libraries and that was more than 10 years ago.
The problem is not the tools, the problem is as everywhere in computing: people hacking without documenting what they do.
5 Likes
This.
Better tools are great of course, but even plain text files of good documentation beat elaborate libraries no one can use because there’s no documentation at all.
1 Like
We even have better than that.
We have the ocamldoc language. It allows to have your documentation exactly where it is needed, in mli files, and will carry itself if you move your sources around.
The ocamldoc language is a fully featured document markup language with sectioning and checked cross references to sections and API entry points.
Doing manuals and tutorial inside .mli always felt a bit cumbersome but is entirely doable as can be witnessed in many of my packages (see this one for example). The good news is that nowadays we will gradually be able to write those larger pieces in seperate .mld files. Code sample extraction is not there yet but I hope we can have a simple design implemented soon rather than having these discussions.
The other good news is that as a programmer, the effort you need to provide in order to make the documentation you write in this language available to end-users is this: approaching zero:
-
If you are using
topkgordune-release(assuming they didn’t kill that workflow), publishing your docs online on github is atopkg distrib && topkg publish docaway. -
Distributing this documentation with your package releases is also automatically done if you use
topkg+ocamlbuildordune: these systems compile and install the right files whichodigcan then pickup in order to generate cross-referenced documentation for all the packages that are installed in youropamswitch and allows you to peacefully read all this wondefully produced documentation offline with the stylesheet that suits you.
One might complain that the ocamldoc language syntax is none of these alternative document markup languages whose popularity or existence came after ocamldoc’s birth but if you ever tried to write a polymorphic variant in a markdown code span you will be glad that ocamldoc’s language isn’t that one.
I understand the ocamldoc language is one more thing to learn as a newcomer but it’s not hugely complex, it’s there, it works with the advantages highlighted above and an aspiring OCaml working programmer shall meet it quite soon anyways since there are thousands of lines of documentation in hundreds of projects that are using it.
3 Likes
Yes, of course we do — my point was that writing documentation at all is more important than how you format it. (That said, given that documentation exists, it’s nice to have it well formatted.)
It would still be nice, I think, if there was a website where the docs for everything in OPAM were kept (and were linked to from the opam.ocaml.org site). That is because often you have no idea if you want to use something before reading the documentation, so having to install it first is a bit of a pain. As it stands, it should be pretty straightforward to do this automatically.
2 Likes
Publishing your own documentation is a bit of a band aid currently. Documentation that isn’t versioned like the packages themselves ends up creating its own set of problems. Cloning a package and checking out the appropriate tag still ends up being the most reliable approach to read accurate docs.
With topkg the watermarking process labels your documentation with version information. Not that it can’t be improved but at least you know what you are reading.
Not really, simply odig what you have installed.
With topkg the watermarking process labels your documentation with version information. Not that it can’t be improved but at least you know what you are reading.
Thanks for informing. I wonder if this is available to odoc generated docs yet.
Not really, simply odig what you have installed.
Disagree. I would like to read the docs for some packages before installing them. Installing an old package can be a highly destructive operation that can lead to build failures, downgrades, and wasted cycles. I would prefer to avoid it if at all possible.