linux-kernel - Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <13c40ed9-a51f-7496-7224-03b563bb6695@gmail.com>
Date:   Fri, 26 Nov 2021 23:33:39 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Hans Verkuil <hverkuil@...all.nl>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org,
        Laurent Pinchart <laurent.pinchart@...asonboard.com>
Subject: Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0

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@...all.nl>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.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