Bug#932957: 'Official' Debian-style html theme for Sphinx-based docs
Hi,
James Addison <jay@jp-hosting.net> wrote (Sun, 14 Apr 2024 23:52:03 +0100):
> 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.
Yes, good catch.
However it's even worse: if you view a German page and use the Search function,
the search index for English is used.
I have tried to deal with this by some adaptions in the cronjob - see the
first two additions in my patch: change all links to search.html into
search.§lang.html, and rename the language-specific searchindex files into
searchindex.$lang.js.
However, that does not seem to be enough.
> 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.
Why is that a problem at all (maybe you know this already):
since we use content negotiation at Debian website (so the pages are
delivered in the correct language according to user's browser setting), we
change the directory structure away from the default how it's build by Sphinx:
after Sphinx' make there are separate directories for every language,
and they contain everything for that language, including the searchindex.js
file. And in that structure it works fine.
On Debian website we put everything in one directory, adding the language
code into the filename in front of the .html extension.
While this works fine for static content, it does not for the search
function here.
> 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.
I don't understand how that could affect our search function problem,
but I could give it a try.
Holger
--
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Reply to: