Bug#932957: 'Official' Debian-style html theme for Sphinx-based docs
On Wed, 17 Apr 2024 at 21:46, Holger Wansing <hwansing@mailbox.org> wrote:
> James Addison <jay@jp-hosting.net> wrote (Sun, 14 Apr 2024 23:52:03 +0100):
> > 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.
>
> I fear I have no idea what to do with these options:
>
> add 'html_file_suffix' in the conf.py: the default value is html here, what
> should I insert here?
A possibility would be to configure it during make, by using something like:
-D html_file_suffix=$*
> in documentation_options.js I have FILE_SUFFIX: '{{ file_suffix }}'; what
> to do with this?
With an html_file_suffix config option, that becomes: FILE_SUFFIX: 'es-ES' (for
example).
> An idea came to mind:
> if we could change the search results, so that they no longer have a file
> extension (say: the link points to 'installing' instead of 'installing.html')
> everything would work fine I guess, since the browser delivers the correct
> language page due to content negotiation according to browser lang settings.
>
>
> I don't know if you thought about such thing, when writing about above html
> build / file suffix options???
> (as already said: I have no clue how the above could change something)
I hadn't considered that approach, but it could make sense since there are
other file formats that we build (text, PDF) and those could also be negotiated
by an HTTP user-agent.
> > 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
> >
>
>
> --
> Holger Wansing <hwansing@mailbox.org>
> PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Reply to: