docs: make tables responsive with content-aware column widths
Subsystems (3)
cover docs: make tables responsive with content-aware column widths
This series establishes a responsive layout foundation for generated tables throughout the documentation site. Wide tables can use contained horizontal scrolling on narrow viewports instead of widening the page or compressing their columns until the content becomes unreadable.
It also derives content-aware minimum widths for each column, giving table content a reasonable floor before wrapping. This prevents aggressive wrapping from collapsing a column's own text into nearly vertical lines and prevents wider columns from squeezing neighboring columns into the same unreadable state.
This addresses the current pathological failure modes in which tables either widen the page beyond its margins or collapse columns into nearly vertical text.
Integration note:
This series is intended to stack on top of Mauro's "docs: custom.css:
don't limit randering to old 800px monitors", retaining its 120em body maximum.
Jon's revert of "docs: allow inline literals in paragraphs to wrap to prevent overflow" should not be carried forward. Patch 2 retains
overflow-wrap: anywhere and prevents the unreadable table wrapping that motivated the revert by adding content-derived column minimums.
Rito Rhymes (2):
docs: apply contained horizontal scroll overflow to tables
docs: derive table column minimum widths from content
Documentation/conf.py | 1 + Documentation/sphinx-static/custom.css | 198 ++++++++++++++++++++++++- Documentation/sphinx/table_layout.py | 136 +++++++++++++++++ 3 files changed, 334 insertions(+), 1 deletion(-) create mode 100644 Documentation/sphinx/table_layout.py
base-commit: a635d6748234582ea287c5ffeae28b9b23f91c7e
Signature · 1 line
2.51.0
PATCH 1/2 docs: apply contained horizontal scroll overflow to tables
Documentation tables can currently fail in two opposite ways on constrained layouts: columns may collapse until their contents wrap into nearly vertical text, or a wide table may expand the document and break the page margins.
Add a foundational containment layer for Sphinx-rendered tables. Wrap each table in an outer container that owns horizontal overflow while leaving the table itself in its native layout mode. This allows wide table content to remain readable through contained scrolling without expanding the page width and breaking the layout.
Applying overflow directly to the table changes its display behavior and causes rendering defects. It can add an outer border that overlaps the table's existing border, making the perimeter appear thicker, and can leave an awkward gap between that outer border and the rightmost column. Keeping overflow on a wrapper avoids those border and caption-layout problems.
The wrapper also provides a useful affordance on narrow viewports. When a table overflows, its right border remains outside the visible area until the user scrolls to reveal it, helping indicate that additional content is available horizontally. Otherwise, showing complete borders on both sides while content is hidden may leave users unaware that the table is scrollable.
Give the wrapper the full width available from the document body. With the 120em body maximum retained, tables can use that space before local scrolling becomes necessary. Tables whose readable width still exceeds the body remain contained and horizontally scrollable rather than widening the page.
This patch establishes the overflow boundary but does not attempt to assign stable widths to table content across all table shapes. Content- derived column minimums are added separately.
---
The following pages demonstrate the two opposite table-layout failures this patch is intended to support.
At a viewport width of 500px or less, a table expands the page width and breaks the layout:
https://docs.kernel.org/7.0/userspace-api/media/v4l/vidioc-enuminput.html
In the 7.1 documentation, the table instead attempts to fit within the viewport by collapsing its columns until some content wraps into nearly vertical text (500px or less):
https://docs.kernel.org/7.1/userspace-api/media/v4l/vidioc-enuminput.html
With both this patch and its follow-up applied, wider tables remain contained within the page and scroll horizontally, including at a viewport width of 500px or less:
https://linux-tables.ritovision.com/userspace-api/media/v4l/vidioc-enuminput.html
The wrapper introduced here provides the horizontal overflow boundary. The follow-up patch adds content-derived column minimums to prevent the vertical text collapse.
The following test cases highlight problems with alternative approaches and explain the implementation choices made by this patch.
Applying the horizontal overflow CSS directly to a table without a wrapper causes a doubled outer border and an empty gap beside the rightmost column.
Test page:
https://docs.kernel.org/7.1/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
Apply the horizontal overflow rules directly to the table instead of an outer wrapper to reproduce the rendering defects.
A body maximum that is too narrow causes contained tables to become locally scrollable at ordinary desktop viewport widths even when unused viewport space remains. The retained 120em body maximum avoids that premature constraint for ordinary layouts, while tables that genuinely exceed the available body width continue to scroll as intended.
Test page:
https://docs.kernel.org/7.1/userspace-api/media/v4l/vidioc-enuminput.html
To reproduce the premature scrolling, reduce the body maximum to 800px while applying contained horizontal overflow.
If a narrower maximum width is later desired for prose, it should be applied selectively to prose or another inner content container rather than globally reducing the width available to table wrappers.
Documentation/conf.py | 1 + Documentation/sphinx-static/custom.css | 11 ++++++++ Documentation/sphinx/table_layout.py | 38 ++++++++++++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 Documentation/sphinx/table_layout.py
Documentation/conf.py +1 -0
@@ -153,6 +153,7 @@ extensions = [ "kernel_feat", "kernel_include", "kfigure", + "table_layout", "maintainers_include", "parser_yaml", "rstFlatTable",
Documentation/sphinx-static/custom.css +11 -0
@@ -27,6 +27,17 @@ div.document { width: auto; } +/* + * Put overflow on an outer container rather than changing the table's display + * type, preserving native table, caption, and collapsed-border rendering. + */ +div.body div.table-overflow { + display: block; + max-width: 100%; + overflow-x: auto; + overflow-y: hidden; +} + /* Size the logo appropriately */ img.logo { width: 104px;
Documentation/sphinx/table_layout.py new file +38 -0
@@ -0,0 +1,38 @@ +# SPDX-License-Identifier: GPL-2.0 +# +"""Provide responsive table layout hooks for HTML documentation. + +Wrap rendered tables in an outer container that enables contained horizontal +scrolling on narrow viewports as needed. Allowing the table to remain wider +than the viewport helps prevent columns from collapsing into unreadable +vertical text, while containing page-wide overflow that would increase the +total page width and break the page margins. Applying overflow directly to the +table instead of the wrapper creates a double-border rendering defect. +""" + +from sphinx.writers.html5 import HTML5Translator + +__version__ = "1.0" + + +class LayoutInjectionHTMLTranslator(HTML5Translator): + """Add HTML containers needed for responsive layout behavior.""" + + def visit_table(self, node): + self.body.append('<div class="table-overflow">\n') + super().visit_table(node) + + def depart_table(self, node): + super().depart_table(node) + self.body.append("</div>\n") + + +def setup(app): + for builder in ("html", "dirhtml", "singlehtml"): + app.set_translator(builder, LayoutInjectionHTMLTranslator, override=True) + + return dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True, + )
Signature · 1 line
2.51.0
PATCH 2/2 docs: derive table column minimum widths from content
In reply to Rito RhymesThe contained overflow wrapper added previously allows wide tables to scroll within the document instead of widening the page. It does not, however, prevent individual columns from collapsing until their contents wrap into narrow, nearly vertical text.
CSS alone cannot derive a useful minimum from the contents of each column. Extend table_layout.py to inspect tables in the resolved doctree and measure the longest normalized single-column cell in each logical column. Assign the resulting table-column-width-N class to every single-column cell in that column.
Track row-spanning cells while traversing each row so later entries remain aligned with their logical columns. Ignore cells that extend across multiple columns when measuring and assigning widths because their content cannot be attributed to one column.
Map the generated classes to ch-based minimum widths in CSS. Limit the derived value to 40 characters and cap each CSS minimum at 60vw so unusually long content cannot create an excessive column floor on narrow viewports. These remain minimums rather than fixed widths, leaving native table layout free to distribute additional space.
Allow otherwise unbreakable table-cell content to wrap anywhere. The generated minimums keep this wrapping from collapsing columns prematurely, while long identifiers, URLs, and inline literals can still break instead of forcing unbounded table expansion. Any remaining table-level width is handled by the contained overflow wrapper.
---
This patch assumes that commit 1afefde902c5 ("Revert \"docs: allow inline literals in paragraphs to wrap to prevent overflow\"") is not carried forward. It retains overflow-wrap: anywhere and addresses the table regression that motivated the revert with content-derived column minimums.
The same table can collapse in opposite directions depending on its content and the generalized CSS rules applied to it. A rule that keeps one column readable can cause another to absorb too much or too little space, creating a whack-a-mole effect where fixing one imbalance introduces another. Because generalized selectors cannot derive a different minimum from the contents of each column, preserving readable widths requires a targeted, per-column solution.
The kgdbreboot parameter table demonstrates two opposite column-collapse failure modes across documentation versions:
To reproduce these failure modes, view each page at a viewport width of 500px or narrower.
v7.1 collapses the left column of inline literals into nearly vertical text while leaving the right column readable:
https://www.kernel.org/doc/html/v7.1/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
v7.0 leaves the left column readable but collapses the right column into nearly vertical text:
https://www.kernel.org/doc/html/v7.0/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
With this series applied, both columns retain readable widths and any remaining table width is contained through horizontal scrolling instead of widening the page:
https://linux-tables.ritovision.com/process/debugging/kgdb.html#run-time-parameter-kgdbreboot
Documentation/sphinx-static/custom.css | 187 ++++++++++++++++++++++++- Documentation/sphinx/table_layout.py | 98 +++++++++++++ 2 files changed, 284 insertions(+), 1 deletion(-)
Documentation/sphinx-static/custom.css +186 -1
@@ -38,6 +38,183 @@ div.body div.table-overflow { overflow-y: hidden; } +/* + * Let long identifiers, URLs, and other unbreakable cell content contribute a + * smaller intrinsic minimum width so the viewport-capped column minimums can + * take effect. Normal text still wraps at ordinary break opportunities; a + * break inside a token is used only when needed to avoid overflow. + */ +div.body table.docutils th, +div.body table.docutils td { + overflow-wrap: anywhere; +} + +/* + * table_layout.py derives a minimum width from the longest non-spanning + * cell in each column and assigns the corresponding table-column-width-N + * class. These minimums prevent premature wrapping, while overflow-wrap: + * anywhere above prevents long tokens from forcing unbounded expansion. + * + * Cap the generated floor at 60vw so an individual column's minimum remains + * fully visible on narrow viewports and does not itself require horizontal + * scrolling to read. Keep this range in sync with MAX_COLUMN_WIDTH. + */ +div.body table.docutils .table-column-width-2 { + min-width: min(2ch, 60vw); +} + +div.body table.docutils .table-column-width-3 { + min-width: min(3ch, 60vw); +} + +div.body table.docutils .table-column-width-4 { + min-width: min(4ch, 60vw); +} + +div.body table.docutils .table-column-width-5 { + min-width: min(5ch, 60vw); +} + +div.body table.docutils .table-column-width-6 { + min-width: min(6ch, 60vw); +} + +div.body table.docutils .table-column-width-7 { + min-width: min(7ch, 60vw); +} + +div.body table.docutils .table-column-width-8 { + min-width: min(8ch, 60vw); +} + +div.body table.docutils .table-column-width-9 { + min-width: min(9ch, 60vw); +} + +div.body table.docutils .table-column-width-10 { + min-width: min(10ch, 60vw); +} + +div.body table.docutils .table-column-width-11 { + min-width: min(11ch, 60vw); +} + +div.body table.docutils .table-column-width-12 { + min-width: min(12ch, 60vw); +} + +div.body table.docutils .table-column-width-13 { + min-width: min(13ch, 60vw); +} + +div.body table.docutils .table-column-width-14 { + min-width: min(14ch, 60vw); +} + +div.body table.docutils .table-column-width-15 { + min-width: min(15ch, 60vw); +} + +div.body table.docutils .table-column-width-16 { + min-width: min(16ch, 60vw); +} + +div.body table.docutils .table-column-width-17 { + min-width: min(17ch, 60vw); +} + +div.body table.docutils .table-column-width-18 { + min-width: min(18ch, 60vw); +} + +div.body table.docutils .table-column-width-19 { + min-width: min(19ch, 60vw); +} + +div.body table.docutils .table-column-width-20 { + min-width: min(20ch, 60vw); +} + +div.body table.docutils .table-column-width-21 { + min-width: min(21ch, 60vw); +} + +div.body table.docutils .table-column-width-22 { + min-width: min(22ch, 60vw); +} + +div.body table.docutils .table-column-width-23 { + min-width: min(23ch, 60vw); +} + +div.body table.docutils .table-column-width-24 { + min-width: min(24ch, 60vw); +} + +div.body table.docutils .table-column-width-25 { + min-width: min(25ch, 60vw); +} + +div.body table.docutils .table-column-width-26 { + min-width: min(26ch, 60vw); +} + +div.body table.docutils .table-column-width-27 { + min-width: min(27ch, 60vw); +} + +div.body table.docutils .table-column-width-28 { + min-width: min(28ch, 60vw); +} + +div.body table.docutils .table-column-width-29 { + min-width: min(29ch, 60vw); +} + +div.body table.docutils .table-column-width-30 { + min-width: min(30ch, 60vw); +} + +div.body table.docutils .table-column-width-31 { + min-width: min(31ch, 60vw); +} + +div.body table.docutils .table-column-width-32 { + min-width: min(32ch, 60vw); +} + +div.body table.docutils .table-column-width-33 { + min-width: min(33ch, 60vw); +} + +div.body table.docutils .table-column-width-34 { + min-width: min(34ch, 60vw); +} + +div.body table.docutils .table-column-width-35 { + min-width: min(35ch, 60vw); +} + +div.body table.docutils .table-column-width-36 { + min-width: min(36ch, 60vw); +} + +div.body table.docutils .table-column-width-37 { + min-width: min(37ch, 60vw); +} + +div.body table.docutils .table-column-width-38 { + min-width: min(38ch, 60vw); +} + +div.body table.docutils .table-column-width-39 { + min-width: min(39ch, 60vw); +} + +div.body table.docutils .table-column-width-40 { + min-width: min(40ch, 60vw); +} + /* Size the logo appropriately */ img.logo { width: 104px;
@@ -171,8 +348,16 @@ div.language-selection ul li:hover { } /* - * Let long inline literals in paragraph text wrap as needed to prevent + * Treat inline literals like normal text for wrapping in ordinary layouts, + * while allowing breaks inside long unbroken tokens when needed to prevent * overflow. + * + * In tables, this aggressive wrapping can otherwise collapse narrow columns + * into nearly vertical text. The content-derived minimum widths assigned by + * table_layout.py establish a readable floor for each column. The column + * width adapts without falling below that floor, while long inline literals + * wrap within the available width rather than forcing the table to expand or + * collapsing into vertical text. */ code.docutils.literal span.pre { white-space: normal;
Documentation/sphinx/table_layout.py +98 -0
117 lines not on this page · raw message
Signature · 1 line
2.51.0
Jonathan Corbet
maintainerQuoted 11 lines · Rito Rhymes
This series establishes a responsive layout foundation for generated tables throughout the documentation site. Wide tables can use contained horizontal scrolling on narrow viewports instead of widening the page or compressing their columns until the content becomes unreadable.
It also derives content-aware minimum widths for each column, giving table content a reasonable floor before wrapping. This prevents aggressive wrapping from collapsing a column's own text into nearly vertical lines and prevents wider columns from squeezing neighboring columns into the same unreadable state.
Quoted 3 lines
This addresses the current pathological failure modes in which tables either widen the page beyond its margins or collapse columns into nearly vertical text.
So I will look at this in more detail in the coming days.
My immediate reaction, though, is that this is the injection of a bunch of complexity to solve a problem that nobody has complained about. Your last attempt here led to regressions that took a while to turn up; I don't really see enough of a reason to risk that again.
Thanks,
jon
Quoted 1 line
So I will look at this in more detail in the coming days.
Thank you, I look forward to the review.
Quoted 2 lines
this is the injection of a bunch of complexity to solve a problem that nobody has complained about.
I don't believe that aligns with the reality, Jon.
In the "bad wrapping in some tables" thread, after I characterized the responsive tables as foundationally pathological throughout the docs site, Hans came in, not to rebut that, but to acknowledge the problems he's seen:
Quoted 4 lines
We're well aware that the tables in the media subsystem do not work well on small screens. The only workable solution would be to move away from tables and format it differently. And that's not going to happen as that would be a massive job.
That is not an absence of a problem. It is a maintainer living with a known pain point because he believed nothing feasible could be done without a massive overhaul.
I believe this series resolves that class of problem without requiring such an overhaul.
My table characterization was also followed immediately by Mauro taking action to foundationally improve how tables render across different viewport sizes (which you then approved).
Quoted 6 lines
On media, I guess the more complex tables with long widths are the pixfmt ones like those:
https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/pixfmt-rgb.html
https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/pixfmt-packed-yuv.html
Quoted 8 lines
It is a good place to check for issues like that.
Please see the patch I submitted:
It moves width support at the html output from previous millennium SVGA-resolutions era to modern age.
Mauro's fix actually opened the gate for my solution here to work properly, allowing contained horizontal scrolling without causing a desktop clipping regression under the previous 800px body constraint.
Quoted 1 line
Your last attempt here led to regressions that took a while to turn up
I own that oversight.
The original fix was targeted at body-text overflow. I did review tables containing inline literals, but I missed the specific case where a column consists only of inline literals, with no other content to preserve a readable width, while surrounding columns compete for space and collapse it. That is a narrow structural edge case, but apparently one with a broad enough surface area here to matter.
I understand this docs system better, and the problem has more eyes on it now.
I'm here to finish the job.
This series addresses that missed case as part of a systemic solution rather than another isolated patch.
Rito
Daniel,
Quoted 1 line
I don't mind testing some stuff if you want me to
Thanks again for offering to do some testing. The series is now posted, and I would appreciate it if you could try it against the tables that prompted the original discussion, along with any other problematic pages you know of.
Would you be able to take a look sometime this week? Testing feedback before Jon reviews the series would be especially useful, if your schedule allows.
Rito
Jonathan Corbet
maintainerQuoted 8 lines · Rito Rhymes
Quoted 1 line
So I will look at this in more detail in the coming days.
Thank you, I look forward to the review.
Quoted 2 lines
this is the injection of a bunch of complexity to solve a problem that nobody has complained about.
I don't believe that aligns with the reality, Jon.
So I have spent a while looking at this change and playing with it. It hasn't really changed my feeling about the whole thing.
You speak repeatedly about rendering on browser windows of widths less than 500px. Who uses such a window? The last Nexus 1 holdout I knew gave up years ago. I would want some sort of indication that this is an actual use case - one with unusually silent users it seems - before trying to address it.
I really don't like the 40-classes hack. CSS makes us do some painful things sometimes, but still ... again, I would have to see that there is a real use case before even considering it.
Just setting max-width doesn't do what you want?
I will listen to what others have to say and, if there is a clamor for the inclusion of this work, I'll consider it further. But, as it stands, my impression still is that it adds a lot of machine-generated complexity that humans will have to maintain going forward for a problem that nobody has complained about.
Thanks,
jon