LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Randy Dunlap <rdunlap@infradead.org>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	Jani Nikula <jani.nikula@linux.intel.com>
Cc: Akira Yokosawa <akiyks@gmail.com>,
	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: Sat, 27 Nov 2021 07:59:13 -0800	[thread overview]
Message-ID: <4c6fe1f6-1a81-1181-f23a-df3f1b538cdf@infradead.org> (raw)
In-Reply-To: <20211127102518.6e715036@coco.lan>

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

  reply	other threads:[~2021-11-27 16:01 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
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 [this message]
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=4c6fe1f6-1a81-1181-f23a-df3f1b538cdf@infradead.org \
    --to=rdunlap@infradead.org \
    --cc=akiyks@gmail.com \
    --cc=corbet@lwn.net \
    --cc=hverkuil@xs4all.nl \
    --cc=jani.nikula@linux.intel.com \
    --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).