lkml.org 
[lkml]   [2021]   [Nov]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0
From
Date
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

\
 
 \ /
  Last update: 2021-11-27 17:02    [W:0.056 / U:0.956 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site