search

ocaml / ocaml.org

The official OCaml website.
https://ocaml.org
Other
161 stars 321 forks source link

the width of polymorphic variants types in the docs #267

Closed arbipher closed 2 weeks ago

arbipher commented 2 years ago

See `Orientation of in Ocamlgraph https://v3.ocaml.org/p/ocamlgraph/2.0.0/doc/Graph/Graphviz/CommonAttributes/index.html#type-graph.Orientation

This is the link (https://backtracking.github.io/ocamlgraph/ocamlgraph/Graph/Graphviz/CommonAttributes/index.html#type-graph.Orientation) to the manual in the package. It looks a bit better maybe due to the width.

sabine commented 2 years ago

This UI issue is particularly bad on smaller screens: there is just not enough space to present things side-by-side.

We can fix this by switching to a format that alternates lines of code and corresponding documentation. The additional use of vertical space would likely be negligible, as we can avoid a lot of line breaks on longer doc strings.

For large enough screens, we could probably tweak the width.

sabine commented 2 years ago

Looking into this rabbit hole a bit more, I think there's three issues here:

  1. The version of odoc used here generates HTML tables for the layout of polymorphic variant types. Looks like this was recently resolved upstream in https://github.com/ocaml/odoc/issues/614 and merged in https://github.com/ocaml/odoc/pull/830/.
  2. The mid column of the page layout shrinks and grows, depending on screen size, assuming many different widths. (An easier-to-design-for layout would guarantee us a workable and predictable minimum-width for the mid column. This could mean collapsing the TOC side bar earlier.)
  3. Even on the widest mid column that the current CSS layout allows, there is currently not enough space to comfortably show the code and documentation side-by-side
tmattio commented 2 weeks ago

I believe this was fixed, I don't see any issue with the link in the description.