Messages in this thread | | | Subject | Re: [PATCH] docs: conf.py: fix support for Readthedocs v 1.0.0 | From | Randy Dunlap <> | Date | Sat, 27 Nov 2021 07:59:13 -0800 |
| |
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
| |