OCaml Documentation Open Thread

I did know. But it works by forking the repo into your github account and doesn’t keep it synced to the original repo, and if you want to test your change it doesn’t help you by showing the results, you need to build the site locally to check.

There’s been little or no change in the content, but I would argue the Sphinx version, merely by being better formatted, is vastly easier to read.

Personally, I find the new coq documentation much harder to navigate. The tactic index – which is the main entry point for the documentation day-to-day – is hidden at the bottom of the side-bar. The tactic index itself is also less pleasant to use.

The content of the new manual is also harder to read just as often as it is easier to read. Everything is far too packed together and the side-bar – which is basically never useful for this manual – occupies a huge amount of screen real estate. There are individual styling changes which make things clearer – the old manual had a habit of having some paragraphs with random indentation and poor delineation between different subsections – but I certainly wouldn’t say it was “vastly” superior.

So I’m not sure how good an advert for “modern typography” this is. I think the new manual looks prettier at a glance, but for actual use it isn’t an improvement.

1 Like

I should point out that I think Sphinx produces nice read-able output for tutorial-style documentation – where there are large bodies of text with the occasional note or code sample. However, for API documentation it tends to degrade into a cluttered mess that is hard to read. This is true of a lot of the markdown/rst based systems – their input just isn’t expressive enough to produce good layouts for API documentation which is light on text.

1 Like

Those are both fixable.

I will have to disagree in two ways. First, the screen real estate is not, in fact, terribly precious, because in practice humans cannot handle wide text displays without having trouble with reading. More than 70 or 90 characters wide and a column starts becoming very difficult for most people to handle. On mobile, screen real estate is precious. On a desktop it is not. (You will note, if you pick up a print book, that there are substantial margins, and that is not because publishers like being extravagant with paper because they’re rolling in money.) Second, having the index right there makes it possible to skip around much more efficiently.

I’ve found it is actually much easier to read. (I’ve discovered that certain things I didn’t think were documented actually were documented, for example.) I’ve heard the same from a number of other people, too.

1 Like

Those are both fixable.

Everything’s fixable. The point is that the most important thing about the documentation is how it is to work with day-to-day, and that sometimes people are willing to sacrifice that in order to get something shinier – which is a shame. The coq manual shouldn’t have been switched until these fairly obvious issues were resolved.

First, the screen real estate is not, in fact, terribly precious, because in practice humans cannot handle wide text displays without having trouble with reading. More than 70 or 90 characters wide and a column starts becoming very difficult for most people to handle.

Humans also read better with a wider margin, which is why the real estate matters. On my screen there is almost no margin between the large bar and the text making it more difficult to focus on the actual content. Similarly, the more clutter on screen the harder it is to read, and here again having a third of the width of the screen taken up by a visually prominent side bar makes it harder to read.

Second, having the index right there makes it possible to skip around much more efficiently.

Except the only place you actually want to skip to – back to the tactics index – is buried off the bottom of the screen.

I’ll switch to the thread on Development of ocaml.org for further comments about that topic.

These are laid out really nicely. Easily the most readable online documentation I have seen. What do they use? Is there a stylesheet that OCaml could steal? (sphinx or otherwise?)

I agree with @lpw25, the Coq stylesheet is certainly more appealing visually than the older one but I don’t find it practical as an API stylesheet. I concur with @n4323 that, for Ocaml APIs, adapting the Racket CSS would be nice (my only fear, w.r.t. the current OCaml stylesheet and that of @dbuenzli, is that the Racket doc is not very dense vertically so I imagine one may have to scroll for kilometers before reaching a given val documentation).

The CSS and underlying structure are easy to steal. I believe the tools are built by the Racket people, but we have similar ones.

This is what the left hand index is for.

I don’t have time to do it immediately, but I will gladly merge any PRs to odoc that make the CSS more Racket-like, or add a left-hand index, especially one that disappears/gets inlined into each page when the page gets smaller.

Regarding the index, see discussion here.

4 Likes

I also want to add that the guide on contributing to CSS is here, and this is the CSS file to edit. It needs a general reorganization and refactoring, so please go ahead and do that if you find the current one difficult to work on.

If more elements need to be rendered by odoc, or the current markup is inconvenient in any way, please open issues, and we can fix it.

To install the development odoc and try everything out, see the instructions. Basically:

  1. Clone and pin the repo:

    git clone https://github.com/ocaml/odoc.git
    cd odoc
    opam pin add --no-action odoc .
    
  2. Install the development odoc:

    opam install odoc
    
  3. Test it on any Jbuilder project:

    jbuilder build @doc
    

    the output will be generated at _build/default/_doc/_html/index.html under the project’s directory.

For editing CSS, you can probably edit it in the browser, then send a PR for the changes. The CSS file odoc generates is just a copy of the one in the repo, and it is at _build/default/_doc/_html/odoc.css, if you’d like to apply the changes there while testing. If you want to apply them, more permanently, to your local odoc clone, edit odoc’s CSS file, then do a commit, and

opam reinstall -y odoc
jbuilder build @doc

to test.

4 Likes

On the topic of live, interactive examples, just in case anyone is not aware yet, OCaml (through BuckleScript) is supported by Klipse, an online in-browser evaluator for interactive code snippets. See this neat article about integrating Klipse+OCaml on your blog. It supports Reason too.

I imagine that since odoc supports raw HTML, integrating Klipse is a matter of copy-pasting the css and scripts to your ocamldoc comments.

(Note that I’ve been meaning to post this since a few days ago, but I couldn’t for the life of me remember the name of the tool. I only remembered it started with a ‘K’ and has an ‘l’ somewhere in it… and today I stumbled again to the Reason 3 blog post and it came back to me.)

4 Likes

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 :slight_smile:
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:

EDIT: vim plugin for instant reStructuredText feedback

2 Likes