sphinx-doc / sphinx-doc/sphinx
The HTML5 writer should render hlist nodes with CSS columns
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
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:
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the hlist handling in sphinx/directives/other.py and the HTML5 writer code in sphinx/writers/html5.py. Trace how the :columns: option reaches the writer, then verify that hlist output uses one list with the requested CSS column count rather than a table of separate lists. Confirm the generated HTML remains valid and accessible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100