LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Akira Yokosawa <akiyks@gmail.com>
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>
Subject: Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
Date: Fri, 26 Nov 2021 23:33:39 +0900	[thread overview]
Message-ID: <13c40ed9-a51f-7496-7224-03b563bb6695@gmail.com> (raw)
In-Reply-To: <f0660b1d24bc9bc07b13fe9a25ccb69ca14e916d.1637923850.git.mchehab+huawei@kernel.org>

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


  parent reply	other threads:[~2021-11-26 14:57 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-26 10:50 Mauro Carvalho Chehab
2021-11-26 11:06 ` Hans Verkuil
2021-11-26 13:06 ` Laurent Pinchart
2021-11-26 14:33 ` Akira Yokosawa [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=13c40ed9-a51f-7496-7224-03b563bb6695@gmail.com \
    --to=akiyks@gmail.com \
    --cc=corbet@lwn.net \
    --cc=hverkuil@xs4all.nl \
    --cc=laurent.pinchart@ideasonboard.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab+huawei@kernel.org \
    --subject='Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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).