Add classes to the odoc HTML page structure.

[dbuenzli]

/cc @Drup I'm being told by @jonludlam

1. Classify the root odoc tree (currently body) as odoc. This closes Replace the content class by odoc #298 and will help stylesheet management/composition if Allow to generate page fragments #374 ever becomes a reality.
2. Classify toplevel nav as odoc-nav (new class)
3. Classify module preamble header as odoc-preamble (new class)
4. Reclassify the toc nav from toc to odoc-toc.
5. Reclassify the content div rom .content to .odoc-content.

Altogether this allows to replace complicated CSS selectors like:

body > nav:first-child { /* toplevel nav */ }

By:

.odoc-nav { /* toplevel-nav */ }

Besides 1. allows to specify odoc page geometry without having to refer to the root tree kind o element (currently body which you won't control if you get embedded).

Pro-tip

To deal with the utterly user-friendly expect test system when you change the markup you want:

CMD=$(make test 2>&1 | grep 'cp '); \
while [ -n "$CMD" ]; do CMD=$(sh -c "$CMD" 2>&1 | grep 'cp '); done

It's slow but at least you don't have to c&p a cli invocation 50 times. Someone ought to fix that madness (I tried various forms of --auto-promote, dune promote without any success).

[dbuenzli]

The ocaml-ci failures seem to be due to mdx which I'm not sure exactly why odoc depends on nowadays. I think it would be good to review a bit the testing structure to simplify it and trim a few dependencies. The fact that there seem to be a mdx git module in odoc should raise some flags.

[jonludlam]

The mdx submodule is temporary. The problem is that we're using mdx for some tests, but mdx depends on the odoc comment parser. The solution is to undo the merge of octavius into odoc and distribute the comment parser as a separate project. Mdx can then depend upon that, and odoc can depend upon mdx, and the dependency cycle will be removed. It's a few days work though as the parser is tangled up with the model and it needs a bit of unravelling.

[dbuenzli]

The problem is that we're using mdx for some tests, but mdx depends on the odoc comment parser.

Dropping the dependency seems a simpler course of action… When I'm testing odoc I don't want to test mdx.

[jonludlam]

yes, but we want to do use mdx to test odoc :-)

[jonludlam]

But this has been a constant source of problems. I'm going to nuke the tests until we can remove the parser.

[Drup]

Sounds good to me. 👍

As for the tests .... I fully agree, I already apply your "pro tip", and it's still a real pain. I don't even actually understand the scripting used for testing and why it's so bad. :/

[dbuenzli]

yes, but we want to do use mdx to test odoc :-)

Well I'll let you judge. But frankly migrate them to something simpler. I heard dune has built-in support for cram testing. That sounds good enough. I'm not sure I see what mdx brings to the party.

The leaner the tooling, the easiest it is to contribute and maintain. I mean I had to install 2 non-opam packages on my system, a bunch of opam packages including one that has a cyclic dependency on odoc and come up with a shell snippet just to be able to run and fix the test suite for a trivial PR.

I'm going to nuke the tests until we can remove the parser.

The parser feels right in odoc. When we had octavius in another repo we had issues flying everywhere; it's not worth the admin overhead, keep it simple.

[lubegasimon]

I heard dune has built-in support for cram testing. That sounds good enough.

Right, it’s something I plan on doing in the coming days, just that there seems to be pressing issues that @jonludlam suggested to be addressed before the next odoc release.

[Drup]

@jonludlam Are we waiting for the new testing for this ? We could merge it as-is (modulo rebase, ofc).

[jonludlam]

I'm going through the PRs now, with some manual testing.

[jonludlam]

Thanks @dbuenzli