Clean up Eio odoc

[talex5]

The only API change is that Hook is now inlined into Switch, as that was its only user.

Some things have been reordered to present them in a better order. Most modules now have more documentation, and often an example.

Note: the docs generated by dune build @doc are very messed up (cc @jonludlam). In particular:

• The spacing makes it appear that comments are attached to the wrong items.
• It renders some types as e.g. Flow.#source, which isn't valid OCaml.
• There are thick blue bars to the left of val for some reason, distracting from the actual name of the value (which is not even in bold).
• The main index page is missing the module descriptions (just says "The entry point of this library is the module: Eio").

Using odig doc things are better, but it likes to underline module names in red for no obvious reason. It also has a fondness for extra semi-colons, e.g. < Flow.source; Flow.close; >.

This worked for me to test it easily, but maybe there's a better way:

git commit -a --amend -m 'WIP' && opam install . && odig odoc eio

I also tried using opam monorepo to allow testing locally, but some dependencies don't work with it yet (e.g. crowbar).

[jonludlam]

• The styling needs some work - I'd very much appreciate someone with ux experience to weigh in with some suggestions :-)
• The Flow.#source thing ought to be fixed by Issue 804 ocaml/odoc#809
• The dune rules are now being looked at properly, and I hope we can make some progress there soon.

[talex5]

The styling needs some work - I'd very much appreciate someone with ux experience to weigh in with some suggestions :-)

I'm not a UX expert, so don't know what anyone else would think of my suggestions ;-) Happy to make some though!

The Flow.#source thing ought to be fixed by ocaml/odoc#809

Hmm, I just tried it with odoc master (2.0.2-43-g3aca7eac), and now I get this, which is also a syntax error:

val stdin : < stdin : Flow.source as 'a.. > -> 'a

For some of the other cases, the # has disappeared completely. e.g. I get:

val load : t -> path -> string

instead of

val load : #t -> path -> string

One other problem I see now that it's linking Flow.source though: it takes you to class definition page, which isn't actually what I want because the objects are supposed to be used by calling functions defined next to the object. So I actually want the link to highlight the type definition in the parent module, but not default to showing its contents, if possible.

[jonludlam]

Until recently classes have been a bit of a second-class citizen in odoc - we've mainly been making sure the module system works correctly. I'm not at all surprised that there are issues with the class paths, but it's something we know needs addressing.