Font size for actual content in Alabaster too small?

Font size for actual content in Alabaster too small?

[Bagas Sanjaya]

Hi,

I have done make htmldocs on linux-next (which includes switching doc theme
to Alabaster) and see the results.

Honestly, the font size for actual content (body) is only 10pt, which makes
reading the docs a bit harder. I think that 12pt should be more readable
instead.

---- >8 ----
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 9b36f7abd24f3f..7894901ca92e4e 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -10,6 +10,10 @@ div.body h3 { font-size: 130%; }
 
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
+
+/* Largen body font size for readability */
+div.body { font-size: 12pt; }
+
 div.sphinxsidebarwrapper { padding: 1em 0.4em; }
 /* Tweak document margins and don't force width */
 div.document {

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: Font size for actual content in Alabaster too small?

[Rui Li]

On 2022/10/31 20:27, Bagas Sanjaya wrote:
> Hi,
>
> I have done make htmldocs on linux-next (which includes switching doc theme
> to Alabaster) and see the results.
>
> Honestly, the font size for actual content (body) is only 10pt, which makes
> reading the docs a bit harder. I think that 12pt should be more readable
> instead.
>
> ---- >8 ----
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 9b36f7abd24f3f..7894901ca92e4e 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -10,6 +10,10 @@ div.body h3 { font-size: 130%; }
>  
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
> +
> +/* Largen body font size for readability */
> +div.body { font-size: 12pt; }
> +
>  div.sphinxsidebarwrapper { padding: 1em 0.4em; }
>  /* Tweak document margins and don't force width */
>  div.document {
>
> Thanks.
>
The text style also makes Chinese characters hard to read in my perspective. And the
font "goudy old style" will let hyphen looks like a dot.

-- 
Rui Li    0x77E6D821D7AE84FE

Re: Font size for actual content in Alabaster too small?

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Hi,
>
> I have done make htmldocs on linux-next (which includes switching doc theme
> to Alabaster) and see the results.
>
> Honestly, the font size for actual content (body) is only 10pt, which makes
> reading the docs a bit harder. I think that 12pt should be more readable
> instead.
>
> ---- >8 ----
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 9b36f7abd24f3f..7894901ca92e4e 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -10,6 +10,10 @@ div.body h3 { font-size: 130%; }
>  
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
> +
> +/* Largen body font size for readability */
> +div.body { font-size: 12pt; }
> +

You didn't notice that I'd already set the font size (seemingly too
small) in conf.py.  The real fix, anyway, is to stop trying to wire font
sizes and let the user's browser settings take control.  So I'm
pondering something like the following...

jon

--------8<--------------


From 236978c7bd9433aea45d5314f31c079e0ef031bb Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Mon, 31 Oct 2022 10:48:19 -0600
Subject: [PATCH] docs: Don't wire font sizes for HTML output

The alabaster theme likes to provide explicit sizes for fonts, which
overrides the users's own browser settings and is guaranteed to displease
folks.  Set the font size to "inherit" so that the users browser settings
control the font size they get.  We can use the font_size configuration
option for the main body font (changing the size I'd already put there),
but the sidebar size can only be set via custom CSS.

Reported-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py                  | 3 ++-
 Documentation/sphinx-static/custom.css | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6ab47833ab6c..c715610d6297 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -316,9 +316,10 @@ if major <= 1 and minor < 8:
 if  html_theme == 'alabaster':
     html_theme_options = {
         'description': get_cline_version(),
-        'font_size': '10pt',
         'page_width': '65em',
         'sidebar_width': '15em',
+        'font_size': 'inherit',
+        'font_family': 'serif',
     }
 
 sys.stderr.write("Using %s theme\n" % html_theme)
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 9b36f7abd24f..45a624fdcf2c 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -11,6 +11,7 @@ div.body h3 { font-size: 130%; }
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
 div.sphinxsidebarwrapper { padding: 1em 0.4em; }
+div.sphinxsidebar { font-size: inherit; }
 /* Tweak document margins and don't force width */
 div.document {
     margin: 20px 10px 0 10px; 
-- 
2.38.1

Re: Font size for actual content in Alabaster too small?

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2600 bytes --]

On Mon, Oct 31, 2022 at 10:52:57AM -0600, Jonathan Corbet wrote:
> 
> You didn't notice that I'd already set the font size (seemingly too
> small) in conf.py.  The real fix, anyway, is to stop trying to wire font
> sizes and let the user's browser settings take control.  So I'm
> pondering something like the following...
> 
> jon
> 
> --------8<--------------
> 
> 
> >From 236978c7bd9433aea45d5314f31c079e0ef031bb Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@lwn.net>
> Date: Mon, 31 Oct 2022 10:48:19 -0600
> Subject: [PATCH] docs: Don't wire font sizes for HTML output
> 
> The alabaster theme likes to provide explicit sizes for fonts, which
> overrides the users's own browser settings and is guaranteed to displease
> folks.  Set the font size to "inherit" so that the users browser settings
> control the font size they get.  We can use the font_size configuration
> option for the main body font (changing the size I'd already put there),
> but the sidebar size can only be set via custom CSS.
> 
> Reported-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py                  | 3 ++-
>  Documentation/sphinx-static/custom.css | 1 +
>  2 files changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 6ab47833ab6c..c715610d6297 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -316,9 +316,10 @@ if major <= 1 and minor < 8:
>  if  html_theme == 'alabaster':
>      html_theme_options = {
>          'description': get_cline_version(),
> -        'font_size': '10pt',
>          'page_width': '65em',
>          'sidebar_width': '15em',
> +        'font_size': 'inherit',
> +        'font_family': 'serif',
>      }
>  
>  sys.stderr.write("Using %s theme\n" % html_theme)
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 9b36f7abd24f..45a624fdcf2c 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -11,6 +11,7 @@ div.body h3 { font-size: 130%; }
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
>  div.sphinxsidebarwrapper { padding: 1em 0.4em; }
> +div.sphinxsidebar { font-size: inherit; }
>  /* Tweak document margins and don't force width */
>  div.document {
>      margin: 20px 10px 0 10px; 

LGTM, thanks.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]