[PATCH 1/2] docs: apply contained horizontal scroll overflow to tables

[Rito Rhymes <rito@ritovision.com>]

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.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: ChatGPT SOL 5.6
---
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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 9b822ab47..53b9eee2e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -153,6 +153,7 @@ extensions = [
     "kernel_feat",
     "kernel_include",
     "kfigure",
+    "table_layout",
     "maintainers_include",
     "parser_yaml",
     "rstFlatTable",
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index aa2a3cf11..e9fc17f5b 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -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;
diff --git a/Documentation/sphinx/table_layout.py b/Documentation/sphinx/table_layout.py
new file mode 100644
index 000000000..029b31ee6
--- /dev/null
+++ b/Documentation/sphinx/table_layout.py
@@ -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,
+    )
-- 
2.51.0