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
