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

[Jonathan Corbet]

Rito Rhymes <rito@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx>
> 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