Integrate OCaml manual in the documentation

[tmattio]

The OCaml manual is still served at v2.ocaml.org. The plan is to migrate the manual to odoc, and use the existing package documentation to serve the manual. This will require work upstream in odoc and the compiler.

[Octachron]

It is important to keep in mind that the "manual" consists in two parts: the manual itself which is written in latex and converted to html by hevea and some post-processing, and the library documentation (both for the standard libraries, the bundled libraries (str, unix,threads) and the compiler libraries). Only the library documentation can be meaningfully converted to odoc.

For the manual itself, my current aim is more to update the html postoprocessing to generate html files that could be more easily integrated into ocaml.org.

[sabine]

@Octachron I have prepared some (non-exhaustive) style changes for the manual at https://github.com/sabine/ocaml/tree/update_manual_styles_to_ocaml_org and there's ideas in #534 on how we could improve the navigation to make switching between versions simpler. (There's a few open questions that we should probably discuss, e.g. whether ocaml.org should add a horizontal navbar on top for the version switcher, or whether the version switcher should be part of the sidebar.)

[cuihtlauac]

@Octachron @sabine: I believe a requirement we should bear in mind is we want everything to look the same, irrelevant of the origin. Maintaining different pieces of CSS, one for each set of HTML is likely to be error-prone and time-consuming. Up to my understanding, I see four groups or pages:

• ocaml.org/docs : md + omd
• ocaml.org/p : odoc
• “the manual itself” : latex + hevea + postprocessing
• “standard library documentation”

[Octachron]

@sabine once you are relatively pleased with your style change, please don't hesitate to submit them upstream (even if the changes are just an incremental improvement).

The standard library document should belongs to the same group as the package documentations ultimately. The only difference that I could see is that the manual links to the standard library documentation pages.

Similarly, I tend to think the manual post-processing should be updated to generate a html structure that doesn't need a different piece of CSS. However, it is true that the manual is more hierarchical than usual subset of the documentation: a manual page has many siblings, and sometimes children which is not the case for the other documentation.

[sabine]

When the plan is to eventually achieve and maintain complete consistency of styles and markup between odoc, ocaml/ocaml and ocaml/ocaml.org, it looks to me like it would be helpful to share styles between all three of these projects. Does that sound reasonable? @Octachron

[Octachron]

Starting with sharing styles (or even making the styles from the ocaml/ocaml side converge towards the ocaml.org ones) sounds like a good idea to me.

[cuihtlauac]

Fixed by #2150