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

[Randy Dunlap]

On 11/27/21 1:25 AM, Mauro Carvalho Chehab wrote:
> Em Sat, 27 Nov 2021 00:03:04 +0200
> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:
>
> > On Fri, 26 Nov 2021, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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@xxxxxxxxx>
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > > > > ---
> > > > >    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