[PATCH RFC] sphinx-static/theme_overrides.css: switch to a fixed width documentation

[PATCH RFC] sphinx-static/theme_overrides.css: switch to a fixed width documentation

[Antonin Godard]

Change the css rules of our theme to have a fixed-width documentation
instead of it taking the full width of the page. I believe this makes it
much more readable compared to having long lines with few line returns,
especially on high-resolution displays. Set the width to 1000px instead
of the previous 800px, which felt slightly too thin.

I think the removed comment here does not make that much sense for us.
It was added by commit 0c1e108bc6c4 ("sphinx: add CSS theme override"),
and I believe is a simply copy and paste of what was is set in the Linux
kernel, added by commit 9abaf979abb2 ("doc-rst: customize RTD theme,
table & full width") [1].

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9abaf979abb2

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Note: this would require backports to stable branches to harmonize each
version of the documentation (perhaps outdated releases too) - either
manually or in an automated manner from the Autobuilder. We would also
have to update the BitBake manual's CSS file.

Note 2: I was hesitant as whether to center the text column or not. If
you want to try this is possible to do it by adding:

.wy-nav-content {
   ...
   margin-left: auto;
   margin-right: auto;
}

Note 3: I also tested this on my smartphone and it displays correctly.
---
 documentation/sphinx-static/theme_overrides.css | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
index d235cb826f..3cb16dbccc 100644
--- a/documentation/sphinx-static/theme_overrides.css
+++ b/documentation/sphinx-static/theme_overrides.css
@@ -99,14 +99,19 @@ em {
 [alt='Permalink'] { color: #eee; }
 [alt='Permalink']:hover { color: black; }
 
+.literal-block {
+    background: #f8f8f8;
+}
+
 @media screen {
-    /* content column
-     *
-     * RTD theme's default is 800px as max width for the content, but we have
-     * tables with tons of columns, which need the full width of the view-port.
-     */
+    .wy-nav-content {
+       max-width: 1000px;
+       background: #fcfcfc;
+    }
 
-    .wy-nav-content{max-width: none; }
+    .wy-nav-content-wrap {
+       background: #efefef;
+    }
 
     /* inline literal: drop the borderbox, padding and red color */
     code, .rst-content tt, .rst-content code {

---
base-commit: b8a56b8b2e8c0417b2f7204f80c79b05d95e9ce4
change-id: 20260202-fixed-width-html-6e5d08767da8

Re: [PATCH RFC] sphinx-static/theme_overrides.css: switch to a fixed width documentation

[Antonin Godard]

On Mon Feb 2, 2026 at 11:47 AM CET, Antonin Godard wrote:
> Change the css rules of our theme to have a fixed-width documentation
> instead of it taking the full width of the page. I believe this makes it
> much more readable compared to having long lines with few line returns,
> especially on high-resolution displays. Set the width to 1000px instead
> of the previous 800px, which felt slightly too thin.
>
> I think the removed comment here does not make that much sense for us.
> It was added by commit 0c1e108bc6c4 ("sphinx: add CSS theme override"),
> and I believe is a simply copy and paste of what was is set in the Linux
> kernel, added by commit 9abaf979abb2 ("doc-rst: customize RTD theme,
> table & full width") [1].
>
> [1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9abaf979abb2

A preview of this patch can be seen at
https://docs.yoctoproject.org/next/index.html.

Any feedback appreciated! I think the docs are more readable like this.

The only drawbacks I would see are:

- Large tables are a bit less readable (but we only have a few: in the release
  notes and on the list of supported features, IIRC).

- Detailed images are not as readable (but can be clicked to be seen fully).

Thanks,
Antonin