LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
* [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
@ 2021-11-26 10:50 Mauro Carvalho Chehab
  2021-11-26 11:06 ` Hans Verkuil
                   ` (2 more replies)
  0 siblings, 3 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2021-11-26 10:50 UTC (permalink / raw)
  To: Linux Doc Mailing List, Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Hans Verkuil, linux-kernel

As described at:
	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs

since Sphinx 1.8, the standard way to setup a custom theme is
to use html_css_files. While using html_context is OK with RTD
0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
producing a very weird html.

Tested with:
	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0

Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 17f7cee56987..7bc72be63fd2 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -249,11 +249,16 @@ except ImportError:
 
 html_static_path = ['sphinx-static']
 
-html_context = {
-    'css_files': [
+if major <= 1 and (minor < 8):
+    html_context = {
+        'css_files': [
+            '_static/theme_overrides.css',
+        ],
+    }
+else:
+    html_css_files = [
         '_static/theme_overrides.css',
-    ],
-}
+    ]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
-- 
2.33.1


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 10:50 [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0 Mauro Carvalho Chehab
@ 2021-11-26 11:06 ` Hans Verkuil
  2021-11-26 13:06 ` Laurent Pinchart
  2021-11-26 14:33 ` Akira Yokosawa
  2 siblings, 0 replies; 10+ messages in thread
From: Hans Verkuil @ 2021-11-26 11:06 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet
  Cc: linux-kernel

On 26/11/2021 11:50, Mauro Carvalho Chehab wrote:
> As described at:
> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
> 
> since Sphinx 1.8, the standard way to setup a custom theme is
> to use html_css_files. While using html_context is OK with RTD
> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
> producing a very weird html.
> 
> Tested with:
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
> 
> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>

Tested-by: Hans Verkuil <hverkuil@xs4all.nl>

Much appreciated! Looks a lot better now :-)

Regards,

	Hans

> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/conf.py | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 17f7cee56987..7bc72be63fd2 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -249,11 +249,16 @@ except ImportError:
>  
>  html_static_path = ['sphinx-static']
>  
> -html_context = {
> -    'css_files': [
> +if major <= 1 and (minor < 8):
> +    html_context = {
> +        'css_files': [
> +            '_static/theme_overrides.css',
> +        ],
> +    }
> +else:
> +    html_css_files = [
>          '_static/theme_overrides.css',
> -    ],
> -}
> +    ]
>  
>  # Add any extra paths that contain custom files (such as robots.txt or
>  # .htaccess) here, relative to this directory. These files are copied
> 


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 10:50 [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0 Mauro Carvalho Chehab
  2021-11-26 11:06 ` Hans Verkuil
@ 2021-11-26 13:06 ` Laurent Pinchart
  2021-11-26 14:33 ` Akira Yokosawa
  2 siblings, 0 replies; 10+ messages in thread
From: Laurent Pinchart @ 2021-11-26 13:06 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, Hans Verkuil, linux-kernel

Hi Mauro,

Thank you for the patch.

On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:
> As described at:
> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
> 
> since Sphinx 1.8, the standard way to setup a custom theme is
> to use html_css_files. While using html_context is OK with RTD
> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
> producing a very weird html.
> 
> Tested with:
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
> 
> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/conf.py | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 17f7cee56987..7bc72be63fd2 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -249,11 +249,16 @@ except ImportError:
>  
>  html_static_path = ['sphinx-static']
>  
> -html_context = {
> -    'css_files': [
> +if major <= 1 and (minor < 8):

No need for parentheses.

> +    html_context = {
> +        'css_files': [
> +            '_static/theme_overrides.css',
> +        ],
> +    }
> +else:
> +    html_css_files = [
>          '_static/theme_overrides.css',
> -    ],
> -}
> +    ]

You could also write

html_css_files = [
    '_static/theme_overrides.css',
]

if major <= 1 and minor < 8:
    html_context = {
        'css_files': html_css_files,
    }

which would be slightly easier to drop when support for sphinx 1.7
(which is the minimum required version) is removed.

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

>  # Add any extra paths that contain custom files (such as robots.txt or
>  # .htaccess) here, relative to this directory. These files are copied

-- 
Regards,

Laurent Pinchart

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 10:50 [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0 Mauro Carvalho Chehab
  2021-11-26 11:06 ` Hans Verkuil
  2021-11-26 13:06 ` Laurent Pinchart
@ 2021-11-26 14:33 ` Akira Yokosawa
  2021-11-26 19:37   ` Randy Dunlap
  2 siblings, 1 reply; 10+ messages in thread
From: Akira Yokosawa @ 2021-11-26 14:33 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Hans Verkuil, linux-doc, linux-kernel, Laurent Pinchart

Hi Mauro,

On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:
> As described at:
> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
> 
> since Sphinx 1.8, the standard way to setup a custom theme is
> to use html_css_files. While using html_context is OK with RTD
> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
> producing a very weird html.
> 
> Tested with:
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
> 
> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/conf.py | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)

So I have an issue with this simple change.
As I said to Jon in another thread [1], in which Jon didn't show any
interest, this update changes the look of generated HTML pages
(I should say) rather drastically, and it looks quite distracting
for my eyes.  The style might be acceptable for API documentations,
but kernel-doc has abundant natural language contents.

[1]: https://lkml.kernel.org/r/550fe790-b18d-f882-4c70-477b596facc7@gmail.com

I think there should be some knobs for customizing the styles.
But I don't know much about css.

Can anybody restore the current look of kernel-doc HTML pages
in a sphinx-rtd-theme-1.0.0-compatible way?

Sidenote:

The change (html_css_files) actually works with
   - Sphinx 1.7.9 + sphinx-rtd-theme 1.0.0

This contradicts the Sphinx documentation saying that html_css_files
was new to Sphinx 1.8.  This might be related to the changes in
sphinx-rtd-theme side, but I have no evidence.

Any suggestion is welcome!

Regards, Akira


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 14:33 ` Akira Yokosawa
@ 2021-11-26 19:37   ` Randy Dunlap
  2021-11-26 22:03     ` Jani Nikula
  0 siblings, 1 reply; 10+ messages in thread
From: Randy Dunlap @ 2021-11-26 19:37 UTC (permalink / raw)
  To: Akira Yokosawa, Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Hans Verkuil, linux-doc, linux-kernel, Laurent Pinchart

On 11/26/21 6:33 AM, Akira Yokosawa wrote:
> Hi Mauro,
> 
> On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:
>> As described at:
>> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
>>
>> since Sphinx 1.8, the standard way to setup a custom theme is
>> to use html_css_files. While using html_context is OK with RTD
>> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
>> producing a very weird html.
>>
>> Tested with:
>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
>> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
>>
>> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> ---
>>   Documentation/conf.py | 13 +++++++++----
>>   1 file changed, 9 insertions(+), 4 deletions(-)
> 
> So I have an issue with this simple change.
> As I said to Jon in another thread [1], in which Jon didn't show any
> interest, this update changes the look of generated HTML pages
> (I should say) rather drastically, and it looks quite distracting
> for my eyes.  The style might be acceptable for API documentations,
> but kernel-doc has abundant natural language contents.

I agree 100% that the sans serif font is not desirable and not as
easy on the eyes as the serif font is.
Hopefully there is a way to change that.

> [1]: https://lkml.kernel.org/r/550fe790-b18d-f882-4c70-477b596facc7@gmail.com
> 
> I think there should be some knobs for customizing the styles.
> But I don't know much about css.
> 
> Can anybody restore the current look of kernel-doc HTML pages
> in a sphinx-rtd-theme-1.0.0-compatible way?
> 
> Sidenote:
> 
> The change (html_css_files) actually works with
>     - Sphinx 1.7.9 + sphinx-rtd-theme 1.0.0
> 
> This contradicts the Sphinx documentation saying that html_css_files
> was new to Sphinx 1.8.  This might be related to the changes in
> sphinx-rtd-theme side, but I have no evidence.
> 
> Any suggestion is welcome!

thanks.
-- 
~Randy

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 19:37   ` Randy Dunlap
@ 2021-11-26 22:03     ` Jani Nikula
  2021-11-27  9:25       ` Mauro Carvalho Chehab
  2021-11-29 21:36       ` Jonathan Corbet
  0 siblings, 2 replies; 10+ messages in thread
From: Jani Nikula @ 2021-11-26 22:03 UTC (permalink / raw)
  To: Randy Dunlap, Akira Yokosawa, Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Hans Verkuil, linux-doc, linux-kernel, Laurent Pinchart

On Fri, 26 Nov 2021, Randy Dunlap <rdunlap@infradead.org> wrote:
> On 11/26/21 6:33 AM, Akira Yokosawa wrote:
>> Hi Mauro,
>> 
>> On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:
>>> As described at:
>>> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
>>>
>>> since Sphinx 1.8, the standard way to setup a custom theme is
>>> to use html_css_files. While using html_context is OK with RTD
>>> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
>>> producing a very weird html.
>>>
>>> Tested with:
>>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
>>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
>>> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
>>>
>>> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---
>>>   Documentation/conf.py | 13 +++++++++----
>>>   1 file changed, 9 insertions(+), 4 deletions(-)
>> 
>> So I have an issue with this simple change.
>> As I said to Jon in another thread [1], in which Jon didn't show any
>> interest, this update changes the look of generated HTML pages
>> (I should say) rather drastically, and it looks quite distracting
>> for my eyes.  The style might be acceptable for API documentations,
>> but kernel-doc has abundant natural language contents.
>
> I agree 100% that the sans serif font is not desirable and not as
> easy on the eyes as the serif font is.
> Hopefully there is a way to change that.

Taking a step back, choosing the sphinx-rtd-theme to begin with was
purely arbitrary, I didn't put much effort into checking the
alternatives, and as far as I recall, neither did Jon. There were more
pressing issues at the time to get the documentation generation ball
rolling at all.

Obviously anyone can change the theme for themselves, and I guess the
question is rather what the default is, and, subsequently, what gets
used at [1].

I haven't followed the development on this closely, but I am somewhat
surprised at the amount of theme overrides having been added, and it
begs the question whether there'd perhaps be a readily available stock
theme that would be better suited than sphinx-rtd-theme?


BR,
Jani.


[1] https://www.kernel.org/doc/html/latest/



>
>> [1]: https://lkml.kernel.org/r/550fe790-b18d-f882-4c70-477b596facc7@gmail.com
>> 
>> I think there should be some knobs for customizing the styles.
>> But I don't know much about css.
>> 
>> Can anybody restore the current look of kernel-doc HTML pages
>> in a sphinx-rtd-theme-1.0.0-compatible way?
>> 
>> Sidenote:
>> 
>> The change (html_css_files) actually works with
>>     - Sphinx 1.7.9 + sphinx-rtd-theme 1.0.0
>> 
>> This contradicts the Sphinx documentation saying that html_css_files
>> was new to Sphinx 1.8.  This might be related to the changes in
>> sphinx-rtd-theme side, but I have no evidence.
>> 
>> Any suggestion is welcome!
>
> thanks.

-- 
Jani Nikula, Intel Open Source Graphics Center

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 22:03     ` Jani Nikula
@ 2021-11-27  9:25       ` Mauro Carvalho Chehab
  2021-11-27 15:59         ` Randy Dunlap
  2021-11-29 21:36       ` Jonathan Corbet
  1 sibling, 1 reply; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2021-11-27  9:25 UTC (permalink / raw)
  To: Jani Nikula
  Cc: Randy Dunlap, Akira Yokosawa, Jonathan Corbet, Hans Verkuil,
	linux-doc, linux-kernel, Laurent Pinchart

Em Sat, 27 Nov 2021 00:03:04 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Fri, 26 Nov 2021, Randy Dunlap <rdunlap@infradead.org> wrote:
> > On 11/26/21 6:33 AM, Akira Yokosawa wrote:  
> >> Hi Mauro,
> >> 
> >> On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:  
> >>> As described at:
> >>> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
> >>>
> >>> since Sphinx 1.8, the standard way to setup a custom theme is
> >>> to use html_css_files. While using html_context is OK with RTD
> >>> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
> >>> producing a very weird html.
> >>>
> >>> Tested with:
> >>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
> >>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
> >>> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
> >>>
> >>> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
> >>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >>> ---
> >>>   Documentation/conf.py | 13 +++++++++----
> >>>   1 file changed, 9 insertions(+), 4 deletions(-)  
> >> 
> >> So I have an issue with this simple change.
> >> As I said to Jon in another thread [1], in which Jon didn't show any
> >> interest, this update changes the look of generated HTML pages
> >> (I should say) rather drastically, and it looks quite distracting
> >> for my eyes.  The style might be acceptable for API documentations,
> >> but kernel-doc has abundant natural language contents.  
> >
> > I agree 100% that the sans serif font is not desirable and not as
> > easy on the eyes as the serif font is.
> > Hopefully there is a way to change that.  

That's actually a bug on my past patch. When html_css_files is used,
it should *not* contain "_static/" at the path. So, it should simply
be:

	html_css_files = [
		'theme_overrides.css',
	]

Just sent a v2 fixing such issue.

> 
> Taking a step back, choosing the sphinx-rtd-theme to begin with was
> purely arbitrary, I didn't put much effort into checking the
> alternatives, and as far as I recall, neither did Jon. There were more
> pressing issues at the time to get the documentation generation ball
> rolling at all.
> 
> Obviously anyone can change the theme for themselves, and I guess the
> question is rather what the default is, and, subsequently, what gets
> used at [1].
> 
> I haven't followed the development on this closely, but I am somewhat
> surprised at the amount of theme overrides having been added, and it
> begs the question whether there'd perhaps be a readily available stock
> theme that would be better suited than sphinx-rtd-theme?

I doubt we'll find one that everybody agrees on, but it sounds worth
discussing it.

One of the things with themes (and with supporting different Sphinx 
versions) is that the look-and-feel changes over time, depending on the 
specific versions that are used. I mean, newer versions of Sphinx come 
with newer css classes, which sometimes replace the output of existing 
tags. 

So, except if either:

1. We stick with just a single Sphinx and theme version; or

2. someone has enough time to keep tracking on mapping each tag's output
   to their css classes and ensure that the look-and-feel will remain 
   the same with all valid version combinations (I don't)

the output will differ depending on the changes at the theme and due
to Sphinx version-dependent output.

Btw, if we look at RTD change log:

	https://sphinx-rtd-theme.readthedocs.io/en/stable/changelog.html

version 1.0.0 basically upgraded the theme to support:
	- Sphinx 4.x
	- Docutils 0.17

It also dropped support for Sphinx version < 1.6.

On other words, by sticking with a non-builtin theme, we may end
needing to apply version-dependent fixes from time to time - mostly
via css override stuff.

-

Perhaps one alternative to help with themes maintenance would be to
select one of the builtin themes from:

	https://sphinx-themes.org/

if they're good enough and are present at the minimal Sphinx version 
supported by Kernel documentation. The ones available on 1.7.9 are:

	$ ls sphinx_1.7.9/lib/python3.10/site-packages/sphinx/themes
	agogo  bizstyle  default  haiku   nonav    scrolls    traditional
	basic  classic   epub     nature  pyramid  sphinxdoc

They all are also the same themes available at the latest version.

If we're willing to do so, I did a quick test here. Those seems to
produce a reasonable output:

	- bizstyle
	- nature
	- classic

If something would still be needed to change, the css override file could
still be used, but keeping it minimal helps to avoid the need of too 
drastic changes.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-27  9:25       ` Mauro Carvalho Chehab
@ 2021-11-27 15:59         ` Randy Dunlap
  2021-12-01 10:16           ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 10+ messages in thread
From: Randy Dunlap @ 2021-11-27 15:59 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jani Nikula
  Cc: Akira Yokosawa, Jonathan Corbet, Hans Verkuil, linux-doc,
	linux-kernel, Laurent Pinchart

On 11/27/21 1:25 AM, Mauro Carvalho Chehab wrote:
> Em Sat, 27 Nov 2021 00:03:04 +0200
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> 
>> On Fri, 26 Nov 2021, Randy Dunlap <rdunlap@infradead.org> wrote:
>>> On 11/26/21 6:33 AM, Akira Yokosawa wrote:
>>>> Hi Mauro,
>>>>
>>>> On Fri, Nov 26, 2021 at 11:50:53AM +0100, Mauro Carvalho Chehab wrote:
>>>>> As described at:
>>>>> 	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs
>>>>>
>>>>> since Sphinx 1.8, the standard way to setup a custom theme is
>>>>> to use html_css_files. While using html_context is OK with RTD
>>>>> 0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
>>>>> producing a very weird html.
>>>>>
>>>>> Tested with:
>>>>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
>>>>> 	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
>>>>> 	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0
>>>>>
>>>>> Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
>>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>>>> ---
>>>>>    Documentation/conf.py | 13 +++++++++----
>>>>>    1 file changed, 9 insertions(+), 4 deletions(-)
>>>>
>>>> So I have an issue with this simple change.
>>>> As I said to Jon in another thread [1], in which Jon didn't show any
>>>> interest, this update changes the look of generated HTML pages
>>>> (I should say) rather drastically, and it looks quite distracting
>>>> for my eyes.  The style might be acceptable for API documentations,
>>>> but kernel-doc has abundant natural language contents.
>>>
>>> I agree 100% that the sans serif font is not desirable and not as
>>> easy on the eyes as the serif font is.
>>> Hopefully there is a way to change that.
> 
> That's actually a bug on my past patch. When html_css_files is used,
> it should *not* contain "_static/" at the path. So, it should simply
> be:
> 
> 	html_css_files = [
> 		'theme_overrides.css',
> 	]
> 
> Just sent a v2 fixing such issue.
> 

Oh, thanks.

>>
>> Taking a step back, choosing the sphinx-rtd-theme to begin with was
>> purely arbitrary, I didn't put much effort into checking the
>> alternatives, and as far as I recall, neither did Jon. There were more
>> pressing issues at the time to get the documentation generation ball
>> rolling at all.
>>
>> Obviously anyone can change the theme for themselves, and I guess the
>> question is rather what the default is, and, subsequently, what gets
>> used at [1].
>>
>> I haven't followed the development on this closely, but I am somewhat
>> surprised at the amount of theme overrides having been added, and it
>> begs the question whether there'd perhaps be a readily available stock
>> theme that would be better suited than sphinx-rtd-theme?
> 
> I doubt we'll find one that everybody agrees on, but it sounds worth
> discussing it.
> 
> One of the things with themes (and with supporting different Sphinx
> versions) is that the look-and-feel changes over time, depending on the
> specific versions that are used. I mean, newer versions of Sphinx come
> with newer css classes, which sometimes replace the output of existing
> tags.
> 
> So, except if either:
> 
> 1. We stick with just a single Sphinx and theme version; or
> 
> 2. someone has enough time to keep tracking on mapping each tag's output
>     to their css classes and ensure that the look-and-feel will remain
>     the same with all valid version combinations (I don't)
> 
> the output will differ depending on the changes at the theme and due
> to Sphinx version-dependent output.
> 
> Btw, if we look at RTD change log:
> 
> 	https://sphinx-rtd-theme.readthedocs.io/en/stable/changelog.html
> 
> version 1.0.0 basically upgraded the theme to support:
> 	- Sphinx 4.x
> 	- Docutils 0.17
> 
> It also dropped support for Sphinx version < 1.6.
> 
> On other words, by sticking with a non-builtin theme, we may end
> needing to apply version-dependent fixes from time to time - mostly
> via css override stuff.
> 
> -
> 
> Perhaps one alternative to help with themes maintenance would be to
> select one of the builtin themes from:
> 
> 	https://sphinx-themes.org/

Looks to me like those are external to sphinx-doc.org. It says that
they are maintained by @pradyunsg and @shirou. (don't know who they are)
There are over 40 themes shown there.

OTOH, there is https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes,
which shows about 12 builtin themes to choose from. Pretty much like the
list the you show just below here...

> 
> if they're good enough and are present at the minimal Sphinx version
> supported by Kernel documentation. The ones available on 1.7.9 are:
> 
> 	$ ls sphinx_1.7.9/lib/python3.10/site-packages/sphinx/themes
> 	agogo  bizstyle  default  haiku   nonav    scrolls    traditional
> 	basic  classic   epub     nature  pyramid  sphinxdoc
> 
> They all are also the same themes available at the latest version.
> 
> If we're willing to do so, I did a quick test here. Those seems to
> produce a reasonable output:
> 
> 	- bizstyle
> 	- nature
> 	- classic

Thanks for checking.

> If something would still be needed to change, the css override file could
> still be used, but keeping it minimal helps to avoid the need of too
> drastic changes.

I'll take a look...


-- 
~Randy

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-26 22:03     ` Jani Nikula
  2021-11-27  9:25       ` Mauro Carvalho Chehab
@ 2021-11-29 21:36       ` Jonathan Corbet
  1 sibling, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2021-11-29 21:36 UTC (permalink / raw)
  To: Jani Nikula, Randy Dunlap, Akira Yokosawa, Mauro Carvalho Chehab
  Cc: Hans Verkuil, linux-doc, linux-kernel, Laurent Pinchart

Jani Nikula <jani.nikula@linux.intel.com> writes:

> Taking a step back, choosing the sphinx-rtd-theme to begin with was
> purely arbitrary, I didn't put much effort into checking the
> alternatives, and as far as I recall, neither did Jon. There were more
> pressing issues at the time to get the documentation generation ball
> rolling at all.

Yeah, I was just happy to see something that worked ... :)

> Obviously anyone can change the theme for themselves, and I guess the
> question is rather what the default is, and, subsequently, what gets
> used at [1].
>
> I haven't followed the development on this closely, but I am somewhat
> surprised at the amount of theme overrides having been added, and it
> begs the question whether there'd perhaps be a readily available stock
> theme that would be better suited than sphinx-rtd-theme?

I've never been hugely pleased with the appearance of the processed
docs, but haven't had a chance to tear into it.  I'll try to look at the
themes Mauro pointed out in the near future.

Meanwhile, I'll go ahead and apply v2 of this patch, thanks.

jon

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
  2021-11-27 15:59         ` Randy Dunlap
@ 2021-12-01 10:16           ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2021-12-01 10:16 UTC (permalink / raw)
  To: Randy Dunlap
  Cc: Jani Nikula, Akira Yokosawa, Jonathan Corbet, Hans Verkuil,
	linux-doc, linux-kernel, Laurent Pinchart

Em Sat, 27 Nov 2021 07:59:13 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> > Perhaps one alternative to help with themes maintenance would be to
> > select one of the builtin themes from:
> > 
> > 	https://sphinx-themes.org/  
> 
> Looks to me like those are external to sphinx-doc.org. It says that
> they are maintained by @pradyunsg and @shirou. (don't know who they are)
> There are over 40 themes shown there.
> 
> OTOH, there is https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes,
> which shows about 12 builtin themes to choose from. Pretty much like the
> list the you show just below here...
> 
> > 
> > if they're good enough and are present at the minimal Sphinx version
> > supported by Kernel documentation. The ones available on 1.7.9 are:
> > 
> > 	$ ls sphinx_1.7.9/lib/python3.10/site-packages/sphinx/themes
> > 	agogo  bizstyle  default  haiku   nonav    scrolls    traditional
> > 	basic  classic   epub     nature  pyramid  sphinxdoc
> > 
> > They all are also the same themes available at the latest version.
> > 
> > If we're willing to do so, I did a quick test here. Those seems to
> > produce a reasonable output:
> > 
> > 	- bizstyle
> > 	- nature
> > 	- classic  
> 
> Thanks for checking.
> 
> > If something would still be needed to change, the css override file could
> > still be used, but keeping it minimal helps to avoid the need of too
> > drastic changes.  
> 
> I'll take a look...

Just sent a patch to help testing/using a different theme:

	https://lore.kernel.org/lkml/8a33f4516c937556b9a38157e236b2f55ef67540.1638353179.git.mchehab+huawei@kernel.org/T/#u

After such patch, you could easily select a different theme during
documentation build, like:

	$ make cleandocs
        $ make SPHINXDIRS=input THEME=classic htmldocs
	$ make SPHINXDIRS=i2c THEME=nature htmldocs

The patch disables the CSS overrides when a theme different than RTD
is used, as the CSS changes there may not be the best with other
themes. It probably make sense to split the contents of the
CSS override to a generic theme, which contains only things that
would apply to all themes (like font selection) from other things
that are theme-dependent, like colors.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2021-12-01 10:16 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-11-26 10:50 [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0 Mauro Carvalho Chehab
2021-11-26 11:06 ` Hans Verkuil
2021-11-26 13:06 ` Laurent Pinchart
2021-11-26 14:33 ` Akira Yokosawa
2021-11-26 19:37   ` Randy Dunlap
2021-11-26 22:03     ` Jani Nikula
2021-11-27  9:25       ` Mauro Carvalho Chehab
2021-11-27 15:59         ` Randy Dunlap
2021-12-01 10:16           ` Mauro Carvalho Chehab
2021-11-29 21:36       ` Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).