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

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>,
	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: Wed, 1 Dec 2021 11:16:44 +0100	[thread overview]
Message-ID: <20211201111644.218b510a@coco.lan> (raw)
In-Reply-To: <4c6fe1f6-1a81-1181-f23a-df3f1b538cdf@infradead.org>

Em Sat, 27 Nov 2021 07:59:13 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

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

Just sent a patch to help testing/using a different theme:

	https://lore.kernel.org/lkml/8a33f4516c937556b9a38157e236b2f55ef67540.1638353179.git.mchehab+huawei@kernel.org/T/#u

After such patch, you could easily select a different theme during
documentation build, like:

	$ make cleandocs
        $ make SPHINXDIRS=input THEME=classic htmldocs
	$ make SPHINXDIRS=i2c THEME=nature htmldocs

The patch disables the CSS overrides when a theme different than RTD
is used, as the CSS changes there may not be the best with other
themes. It probably make sense to split the contents of the
CSS override to a generic theme, which contains only things that
would apply to all themes (like font selection) from other things
that are theme-dependent, like colors.

Thanks,
Mauro