To:     Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Hans Verkuil <hverkuil@xs4all.nl>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        Laurent Pinchart <laurent.pinchart@ideasonboard.com>
References: <f0660b1d24bc9bc07b13fe9a25ccb69ca14e916d.1637923850.git.mchehab+huawei@kernel.org>
Subject: Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
From:   Akira Yokosawa <akiyks@gmail.com>
Message-ID: <13c40ed9-a51f-7496-7224-03b563bb6695@gmail.com>
Date:   Fri, 26 Nov 2021 23:33:39 +0900
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.14.0
MIME-Version: 1.0
In-Reply-To: <f0660b1d24bc9bc07b13fe9a25ccb69ca14e916d.1637923850.git.mchehab+huawei@kernel.org>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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