Add support for tables

[gpetiot]

Support new syntax added in ocaml-doc/odoc-parser#11

[panglesd]

According to caniuse, only 75% of viewer use a browser which support the colgroup tag (88% on desktop) (the main culprit is old versions of safari on iOS).

75/88% might be good enough, or not, but since the code is generated, it is as easy to give each td/th items of each line the style (or class) that align them, instead of using colgroup.

[panglesd]

Now that ocaml-doc/odoc-parser#11 has been merged, this PR is ready for review!

What is the best way to run the tests before the parser is released? Should we temporarily pin odoc-parser?

[panglesd]

I added support for alignment in the latex backend, using the array latex package.
So, \usepackage{array} need to be added to the latex preamble for array alignment to work (array without alignment and no array do not need modification in the preamble).

I tested the array addition it on the ocaml manual and it seems to not change anything (array is supposed to be retrocompatible with original tabular environment).

The man backend does not have support for alignment.

[panglesd]

I finished support for the man backend, including adding support for alignment.

The support is restricted to what the target syntax allows, though. Nested tables in man pages won't render, without warning.

Depends on ocaml-doc/odoc-parser#14 to pass the tests.

[gpetiot]

For me it's good to be merged as soon as ocaml-doc/odoc-parser#14 is merged

[panglesd]

Need to be rebased on #950 for CI to pass!

[trefis]

I left a few comments here and there.

I haven't looked in details at the latex and man backends, I personally trust that you've tested that they work.
However, I guess @Octachron might want to have a look? (And perhaps @dbuenzli as well, for the manpage one?)

[trefis]

This question might already have been answered (in which case: apologies) but: why is the table nested in a <div>?
Why is this not mk_block Html.table ~extra_class:"odoc-table" [ mk_rows ~config ~resolve t ]?

[panglesd]

I think it should be mk_block Html.table ~extra_class:"odoc-table" [ mk_rows ~config ~resolve t ]. I changed it.

[trefis]

Meh.
This leads to ugly code in the html backend, and some "normalisation" in the latex one.
Perhaps we could normalize when we create the elements, instead of when we render them; so align : alignment option list?

Furthermore: I assume the polymorphic variants are here because the parser emits them, but:

1. I'm not a fan
2. If we're already doing some datatype mapping from the parser to odoc types, let's go a bit further:

   type alignment  = Default | Left | Center | Right
   type 'a t = {
     date : ...;
     align: alignment list;
   }

[panglesd]

I agree with removing the polymorphic variant.
I don't mind using Default instead of None.
I think I delayed the "compute the number of columns when alignment is unspecified" since it's not always needed, but I agree it's not ideal, so I implemented your proposition, which seems better.

[panglesd]

• About the latex backend:

For alignment to work, you have to add \usepackage{array} to the preamble of the latex file.
The array package is a compatible extension of the original array environment, it was needed to specify both alignment and cell width.
I tried to add this package to the ocaml manual preamble and build the docs, and I could not notice any difference. So I think it is a safe to require it for aligned arrays without breaking existing things.

Adding this package is not required if there is no tables with specified alignment in the documentation.

• About the manpage:

I used tbl, with the following documentation: https://manpages.debian.org/testing/groff-base/tbl.1.en.html
The manpage backend suffers from some limitations (alignment does not work well, nested tables do not work) but I think the support is already sufficient.

[trefis]

Will merge tomorrow morning unless someone disagrees.

[Octachron]

I had a quick glance at the latex backend and it looks fine to me (and we can always amend it if we discover issues later).