sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

The HTML5 writer should render hlist nodes with CSS columns

Open Screwtapello opened this issue 3 years ago • 1 comments

Currently, Sphinx includes the hlist directive which produces a bulleted list split into multiple columns. Internally, it splits the list up into as many equal-sized pieces as there are columns. The HTML5 writer renders this by constructing a one-row table with a list in each column:

https://github.com/sphinx-doc/sphinx/blob/f45dc5e1398f7850e23003cac200ad3433da2a78/sphinx/writers/html5.py#L637-L647

The problem with this approach is that it only checks that each column has the same number of items. If some items are a little long and get wrapped across two lines at some zoom levels (or with some fonts, or on some platforms) the whole list can look quite messy. In addition, there's probably accessibility issues (screen readers, etc.) when one list is presented as four separate lists.

But browsers already have a solution to this problem, in the form of the column-count CSS property. Instead of a complex structure of table and lists, Sphinx could just change the typical bulleted-list output from <ul> to <ul style="column-count: 3"> (or whatever the value of the :columns: option is). The Sphinx code would be simpler since it doesn't have to slice up the list, it would be more accessible since a single list in the source would be a single list in the HTML, and it would be robust in the face of runtime layout because the runtime layout engine is doing the work.

Screwtapello avatar Aug 05 '22 09:08 Screwtapello