[PATCH 0/1] docs: examples of pages affected by table overflow

[PATCH 0/1] docs: examples of pages affected by table overflow

[Rito Rhymes]

Examples of affected pages this patch improves:
  kernel-hacking/locking.html
  arch/arc/features.html
  arch/arm/memory.html
  arch/arm/omap/dss.html
  arch/mips/features.html
  arch/nios2/features.html
  arch/openrisc/features.html
  arch/parisc/features.html
  arch/powerpc/features.html
  arch/riscv/features.html
  arch/s390/features.html
  arch/sparc/features.html
  arch/x86/boot.html
  arch/x86/zero-page.html
  arch/x86/pat.html
  arch/x86/amd-hfi.html
  arch/x86/tsx_async_abort.html
  arch/x86/features.html
  driver-api/parport-lowlevel.html

Rito Rhymes (1):
  docs: wrap generated tables to contain small-screen overflow

 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 16 ++++++++++++++
 Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 Documentation/sphinx/table_wrapper.py

-- 
2.51.0

[PATCH 1/1] docs: wrap generated tables to contain small-screen overflow

[Rito Rhymes]

Some documentation tables exceed the fixed-width main content column.
On desktop this is usually acceptable because they can overflow the
800px body without harming readability, but on smaller screens the
same tables create page-wide horizontal scroll overflow that breaks the
layout.

Wrap generated HTML tables in a dedicated container. Above
Alabaster's existing 65em breakpoint, the wrapper uses
`display: contents` to preserve current desktop rendering. At and
below that width, it becomes a horizontal scroll container so table
overflow is contained locally instead of breaking page layout.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
---
 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 16 ++++++++++++++
 Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 Documentation/sphinx/table_wrapper.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..51756d779 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -159,6 +159,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.ifconfig",
+    "table_wrapper",
     "translations",
 ]
 # Since Sphinx version 3, the C function parser is more pedantic with regards
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..d7c8c4f18 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -23,6 +23,13 @@ div.document {
     margin: 20px 10px 0 10px;
     width: auto;
 }
+/*
+ * Wrap generated tables in a container that preserves desktop overflow
+ * while allowing contained scrolling on smaller screens.
+ */
+div.body div.table-overflow {
+    display: contents;
+}
 
 /* Size the logo appropriately */
 img.logo {
@@ -96,6 +103,15 @@ input.kernel-toc-toggle { display: none; }
     div.kerneltoc a { color: black; }
 }
 
+@media screen and (max-width: 65em) {
+    div.body div.table-overflow {
+        display: block;
+        max-width: 100%;
+        overflow-x: auto;
+        overflow-y: hidden;
+    }
+}
+
 /* Language selection menu */
 
 div.admonition {
diff --git a/Documentation/sphinx/table_wrapper.py b/Documentation/sphinx/table_wrapper.py
new file mode 100644
index 000000000..dfe8c139b
--- /dev/null
+++ b/Documentation/sphinx/table_wrapper.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+"""Wrap generated HTML tables in a responsive overflow container."""
+
+from sphinx.writers.html5 import HTML5Translator
+
+__version__ = "1.0"
+
+
+class TableWrapperHTMLTranslator(HTML5Translator):
+    """Add a wrapper around tables so CSS can control overflow 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, TableWrapperHTMLTranslator, override=True)
+
+    return dict(
+        version=__version__,
+        parallel_read_safe=True,
+        parallel_write_safe=True,
+    )
-- 
2.51.0

Re: [PATCH 1/1] docs: wrap generated tables to contain small-screen overflow

[Randy Dunlap]

On 3/21/26 6:38 AM, Rito Rhymes wrote:
> Some documentation tables exceed the fixed-width main content column.
> On desktop this is usually acceptable because they can overflow the
> 800px body without harming readability, but on smaller screens the
> same tables create page-wide horizontal scroll overflow that breaks the
> layout.
> 
> Wrap generated HTML tables in a dedicated container. Above
> Alabaster's existing 65em breakpoint, the wrapper uses
> `display: contents` to preserve current desktop rendering. At and
> below that width, it becomes a horizontal scroll container so table
> overflow is contained locally instead of breaking page layout.

Yes, I can (did) observe that happening (horizontal slider bar).
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> ---
>  Documentation/conf.py                  |  1 +
>  Documentation/sphinx-static/custom.css | 16 ++++++++++++++
>  Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
>  3 files changed, 47 insertions(+)
>  create mode 100644 Documentation/sphinx/table_wrapper.py

-- 
~Randy

[PATCH v2 0/1] docs: examples of pages affected by table overflow

[Rito Rhymes]

Examples of affected pages this patch improves:
  kernel-hacking/locking.html
  arch/arc/features.html
  arch/arm/memory.html
  arch/arm/omap/dss.html
  arch/mips/features.html
  arch/nios2/features.html
  arch/openrisc/features.html
  arch/parisc/features.html
  arch/powerpc/features.html
  arch/riscv/features.html
  arch/s390/features.html
  arch/sparc/features.html
  arch/x86/boot.html
  arch/x86/zero-page.html
  arch/x86/pat.html
  arch/x86/amd-hfi.html
  arch/x86/tsx_async_abort.html
  arch/x86/features.html
  driver-api/parport-lowlevel.html

Rito Rhymes (1):
  docs: wrap generated tables to contain small-screen overflow

 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 16 ++++++++++++++
 Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 Documentation/sphinx/table_wrapper.py

-- 
2.51.0

[PATCH v2 1/1] docs: wrap generated tables to contain small-screen overflow

[Rito Rhymes]

Some documentation tables exceed the fixed-width main content column.
On desktop this is usually acceptable because they can overflow the
800px body without harming readability, but on smaller screens the
same tables create page-wide horizontal scroll overflow that breaks the
layout.

Wrap generated HTML tables in a dedicated container. Above
Alabaster's existing 65em breakpoint, the wrapper uses
`display: contents` to preserve current desktop rendering. At and
below that width, it becomes a horizontal scroll container so table
overflow is contained locally instead of breaking page layout.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v2: add Assisted-by attribution

 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 16 ++++++++++++++
 Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 Documentation/sphinx/table_wrapper.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..51756d779 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -159,6 +159,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.ifconfig",
+    "table_wrapper",
     "translations",
 ]
 # Since Sphinx version 3, the C function parser is more pedantic with regards
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..d7c8c4f18 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -23,6 +23,13 @@ div.document {
     margin: 20px 10px 0 10px;
     width: auto;
 }
+/*
+ * Wrap generated tables in a container that preserves desktop overflow
+ * while allowing contained scrolling on smaller screens.
+ */
+div.body div.table-overflow {
+    display: contents;
+}
 
 /* Size the logo appropriately */
 img.logo {
@@ -96,6 +103,15 @@ input.kernel-toc-toggle { display: none; }
     div.kerneltoc a { color: black; }
 }
 
+@media screen and (max-width: 65em) {
+    div.body div.table-overflow {
+        display: block;
+        max-width: 100%;
+        overflow-x: auto;
+        overflow-y: hidden;
+    }
+}
+
 /* Language selection menu */
 
 div.admonition {
diff --git a/Documentation/sphinx/table_wrapper.py b/Documentation/sphinx/table_wrapper.py
new file mode 100644
index 000000000..dfe8c139b
--- /dev/null
+++ b/Documentation/sphinx/table_wrapper.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+"""Wrap generated HTML tables in a responsive overflow container."""
+
+from sphinx.writers.html5 import HTML5Translator
+
+__version__ = "1.0"
+
+
+class TableWrapperHTMLTranslator(HTML5Translator):
+    """Add a wrapper around tables so CSS can control overflow 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, TableWrapperHTMLTranslator, override=True)
+
+    return dict(
+        version=__version__,
+        parallel_read_safe=True,
+        parallel_write_safe=True,
+    )
-- 
2.51.0

[PATCH v3] docs: wrap generated tables to contain small-screen overflow

[Rito Rhymes]

Some documentation tables exceed the fixed-width main content column.
On desktop this is usually acceptable because they can overflow the
800px body without harming readability, but on smaller screens the
same tables create page-wide horizontal scroll overflow that breaks the
layout.

Wrap generated HTML tables in a dedicated container. Above
Alabaster's existing 65em breakpoint, the wrapper uses
`display: contents` to preserve current desktop rendering. At and
below that width, it becomes a horizontal scroll container so table
overflow is contained locally instead of breaking page layout.

Examples:
  https://docs.kernel.org/6.15/kernel-hacking/locking.html
  https://docs.kernel.org/6.15/arch/arc/features.html

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v3: add latest public versioned URL examples to the patchlog

 Documentation/conf.py                  |  1 +
 Documentation/sphinx-static/custom.css | 16 ++++++++++++++
 Documentation/sphinx/table_wrapper.py  | 30 ++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 Documentation/sphinx/table_wrapper.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..51756d779 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -159,6 +159,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.ifconfig",
+    "table_wrapper",
     "translations",
 ]
 # Since Sphinx version 3, the C function parser is more pedantic with regards
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..d7c8c4f18 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -23,6 +23,13 @@ div.document {
     margin: 20px 10px 0 10px;
     width: auto;
 }
+/*
+ * Wrap generated tables in a container that preserves desktop overflow
+ * while allowing contained scrolling on smaller screens.
+ */
+div.body div.table-overflow {
+    display: contents;
+}
 
 /* Size the logo appropriately */
 img.logo {
@@ -96,6 +103,15 @@ input.kernel-toc-toggle { display: none; }
     div.kerneltoc a { color: black; }
 }
 
+@media screen and (max-width: 65em) {
+    div.body div.table-overflow {
+        display: block;
+        max-width: 100%;
+        overflow-x: auto;
+        overflow-y: hidden;
+    }
+}
+
 /* Language selection menu */
 
 div.admonition {
diff --git a/Documentation/sphinx/table_wrapper.py b/Documentation/sphinx/table_wrapper.py
new file mode 100644
index 000000000..dfe8c139b
--- /dev/null
+++ b/Documentation/sphinx/table_wrapper.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+"""Wrap generated HTML tables in a responsive overflow container."""
+
+from sphinx.writers.html5 import HTML5Translator
+
+__version__ = "1.0"
+
+
+class TableWrapperHTMLTranslator(HTML5Translator):
+    """Add a wrapper around tables so CSS can control overflow 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, TableWrapperHTMLTranslator, override=True)
+
+    return dict(
+        version=__version__,
+        parallel_read_safe=True,
+        parallel_write_safe=True,
+    )
-- 
2.51.0

Re: [PATCH v3] docs: wrap generated tables to contain small-screen overflow

[Jonathan Corbet]

Rito Rhymes <rito@ritovision.com> writes:

> Some documentation tables exceed the fixed-width main content column.
> On desktop this is usually acceptable because they can overflow the
> 800px body without harming readability, but on smaller screens the
> same tables create page-wide horizontal scroll overflow that breaks the
> layout.
>
> Wrap generated HTML tables in a dedicated container. Above
> Alabaster's existing 65em breakpoint, the wrapper uses
> `display: contents` to preserve current desktop rendering. At and
> below that width, it becomes a horizontal scroll container so table
> overflow is contained locally instead of breaking page layout.
>
> Examples:
>   https://docs.kernel.org/6.15/kernel-hacking/locking.html
>   https://docs.kernel.org/6.15/arch/arc/features.html
>
> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> Assisted-by: Codex:GPT-5.4

[...]

> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index db24f4344..d7c8c4f18 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -23,6 +23,13 @@ div.document {
>      margin: 20px 10px 0 10px;
>      width: auto;
>  }
> +/*
> + * Wrap generated tables in a container that preserves desktop overflow
> + * while allowing contained scrolling on smaller screens.
> + */
> +div.body div.table-overflow {
> +    display: contents;
> +}
>  
>  /* Size the logo appropriately */
>  img.logo {
> @@ -96,6 +103,15 @@ input.kernel-toc-toggle { display: none; }
>      div.kerneltoc a { color: black; }
>  }
>  
> +@media screen and (max-width: 65em) {
> +    div.body div.table-overflow {
> +        display: block;
> +        max-width: 100%;
> +        overflow-x: auto;
> +        overflow-y: hidden;
> +    }
> +}
> +
>  /* Language selection menu */

So this CSS perhaps makes sense, but..

>  div.admonition {
> diff --git a/Documentation/sphinx/table_wrapper.py b/Documentation/sphinx/table_wrapper.py
> new file mode 100644
> index 000000000..dfe8c139b
> --- /dev/null
> +++ b/Documentation/sphinx/table_wrapper.py
> @@ -0,0 +1,30 @@
> +# SPDX-License-Identifier: GPL-2.0
> +#
> +"""Wrap generated HTML tables in a responsive overflow container."""
> +
> +from sphinx.writers.html5 import HTML5Translator
> +
> +__version__ = "1.0"
> +
> +
> +class TableWrapperHTMLTranslator(HTML5Translator):
> +    """Add a wrapper around tables so CSS can control overflow 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, TableWrapperHTMLTranslator, override=True)
> +
> +    return dict(
> +        version=__version__,
> +        parallel_read_safe=True,
> +        parallel_write_safe=True,
> +    )

But why do you need to inject another <div>, creating a whole new
extension to do so, rather than just applying the CSS directly to the
<table> elements?  I just gave that a try, and it would appear to work
just fine.

Thanks,

jon

Re: [PATCH v3] docs: wrap generated tables to contain small-screen overflow

[Rito Rhymes]

> So this CSS perhaps makes sense, but..
> But why do you need to inject another <div>, creating a whole
> new extension to do so, rather than just applying the CSS
> directly to the <table> elements? I just gave that a try, and
> it would appear to work just fine.

I did try applying it directly to the <table> elements.

That works on some pages, but in my testing it introduces
regressions on others that do not happen with the wrapper
approach.

For example, on `/bpf/standardization/instruction-set.html` at
400px viewport width, applying CSS scrollability directly to
the table creates an extra outer border with an awkward gap and,
more importantly, causes cell content to wrap much more
aggressively as the viewport narrows. Instead of letting the
table remain a readable horizontally scrollable unit, the text
gets squeezed into very narrow stacked lines that are harder
to read.

Screenshots:
Double border with gap issue highlighted -
https://github.com/user-attachments/assets/0ddacc4e-edce-4c14-b129-0940e8014d3f
Text wrapping issue highlighted -
https://github.com/user-attachments/assets/c172e126-7a4c-4b3c-a01c-fd4c8f08bda6

On `/arch/arc/features.html`, the wrapping issue is not present
and it scrolls fine, but I still see the double-border issue
there. In that case there is no gap, so it mainly looks like a
thicker border.

The reason for the wrapper is that it gives one consistent
overflow treatment across the existing table cases without
changing the table element's layout behavior directly. In my
testing, applying the scrollability to the <table> itself
works for some pages but regresses others, while the wrapper
approach avoids needing targeted CSS rules for different
rendered table cases.

If helpful, you're welcome to add any screenshots as a
comment on this GitHub issue:
https://github.com/ritovision/linux-kernel-docs/issues/1

Rito

Re: [PATCH v3] docs: wrap generated tables to contain small-screen overflow

[Rito Rhymes]

Jon,

Following up on this point:

> So this CSS perhaps makes sense, but.. But why do you need to inject
> another <div>, creating a whole new extension to do so, rather than
> just applying the CSS directly to the <table> elements? I just gave
> that a try, and it would appear to work just fine.

In my previous reply I outlined the regressions I saw when applying the
CSS directly to the `<table>` elements, and why that led me to the
wrapper-based approach instead.

Given the regressions and rationale I already outlined, is the
wrapper-based approach acceptable?

Thanks,
Rito