Re: [PATCH RFC] Documentation: typography refresh

[Mauro Carvalho Chehab]

Em Thu, 19 Jun 2025 11:23:19 +0700
Bagas Sanjaya <bagasdotme@xxxxxxxxx> escreveu:

> At present, kernel documentation uses system serif font for body text.
> Some people, however, objected to it and instead prefer that the
> typography choice must be legible, consistent, and accessible (after
> all, the audience ranges developers peeking into kernel internals to
> ordinary users that skimmed through Documentation/admin-guide/).
> 
> To tackle the problem, follow Wikimedia's typography refresh [1].
> For the font choices, instead of using web fonts as in previous
> attempt [2], use:
> 
>   * Linux Libertine, Georgia, Times for serif (used in h1 and h2
>     headings)
>   * system font for sans-serif and monospace
> 
> This allows for more readability and consistency without sacrificing
> page load times and bandwidth, as the font choices is most likely
> already available on many platforms.
> 
> The reason why serif fonts is used for headings in complement to sans
> serif in text body is to break up visual monotony of docs page by
> creating contrast between headings (as entry point to docs information)
> and text body, which is important considering that kernel docs are
> quite lengthy with many sections.
> 
> For body text (excluding sidebar), it is set to #252525 on top
> of #FFFFFF background as they have contrast ratio 15.3:1, which
> is rated as AAA according to WCAG 2.0 section 1.4.6. Having slightly
> off-black foreground text on white background can reduce eye strain
> and juxtaposition on dyslexic readers.
> 
> This refresh only applies to default Alabaster theme.
> 
> [1]: https://www.mediawiki.org/wiki/Typography_refresh
> [2]: https://lore.kernel.org/linux-doc/20231102123225.32768-1-bagasdotme@xxxxxxxxx/
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> ---
>  Documentation/conf.py                      |  5 +-
>  Documentation/sphinx-static/typography.css | 62 ++++++++++++++++++++++
>  2 files changed, 66 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/sphinx-static/typography.css
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 12de52a2b17e78..f5713cd70cc17c 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -310,9 +310,12 @@ if  html_theme == 'alabaster':
>          'sidebar_width': '15em',
>          'fixed_sidebar': 'true',
>          'font_size': 'inherit',
> -        'font_family': 'serif',
>      }
>  
> +    html_css_files  = [
> +        'typography.css',
> +    ]
> +
>  sys.stderr.write("Using %s theme\n" % html_theme)

I liked this part: having fonts inside a css. However the code is broken,
as there are already several parts of conf.py which alrease sets
html_css_files on different ways, depending on two make vars. From
make help:

	make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.
	make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.

The code on conf.py in question is:

	if html_theme in ["sphinx_rtd_theme", "sphinx_rtd_dark_mode"]:
		...
	        html_css_files = [
	            "theme_overrides.css",
	        ]
		...
		if html_theme == "sphinx_rtd_theme":
	            # Add color-specific RTD normal mode
            html_css_files.append("theme_rtd_colors.css")
	...
	if "DOCS_CSS" in os.environ:
	    css = os.environ["DOCS_CSS"].split(" ")

	    for l in css:
	        html_css_files.append(l)

You can't just replace html_css_files without considering the above,
specially since one could be doing DOCS_CSS="some_other_typography.css".

IMO, the code should be instead:

	if html_theme == "alabaster":
	    if not html_css_files:
	        html_css_files  = [ "typography.css" ]

E.g. only use it if:
- the theme is the default one;
- the Kernel docs will be built without DOCS_CSS.

Thanks,
Mauro