Bug#932957: 'Official' Debian-style html theme for Sphinx-based docs
Hi Holger,
On Sun, 14 Apr 2024 22:40:36 +0200, Holger wrote:
> I forgot to mention, that I have pushed a release-notes variant with this
theme to
> https://people.debian.org/~holgerw/new-rtd-sphinx-theme-for-debian/release-notes/release-notes/index.en.html
> (English)
>
> https://people.debian.org/~holgerw/new-rtd-sphinx-theme-for-debian/release-notes/release-notes/index.de.html
> (German)
>
> https://people.debian.org/~holgerw/new-rtd-sphinx-theme-for-debian/release-notes/release-notes/index.ca.html
> (Catalan)
>From some testing of these: the search results have a problem that they
hyperlink to a language-less .html URL, meaning that clicking a result link in
the DE-language search results takes the user to a EN-language page.
The _other_ hyperlinks in the static content are replaced as part of the
cronjob[1] - but that doesn't work for items in the searchindex.js file.
Fortunately I think there might be a better way to do this. Sphinx itself has
an HTML builder option 'html_file_suffix' and I think we could use that instead
to define the filenames. That option is respected by the search JavaScript
using a template variable[3] in the documentation_options.js file.
We should be careful of other side-effects if making that change, but it
would remove a deployment transformation step on the static content, and I
think that's beneficial.
[1] - https://salsa.debian.org/webmaster-team/cron/-/blob/3462a061d0a67dce3761b0f4d9357c017ad0a50b/parts/7release-notes#L64-70
[2] - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_file_suffix
[3] - https://github.com/sphinx-doc/sphinx/blob/cf7d2759af0852d67288e58d823d51fe860749ca/sphinx/themes/basic/static/documentation_options.js_t#L6
Reply to: