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

[Randy Dunlap <rdunlap@infradead.org>]

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