taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit 64b4f06b57c70d4e0fa6feab81ec20f155e0b9c2
parent 93c3306c9d19a34866c6cb0da43b3cb12f100222
Author: Florian Dold <dold@taler.net>
Date:   Tue, 10 Nov 2026 19:11:00 +0100

docs: restore sidebar toggle for affected theme builds

Older Book/PyData builds open the mobile drawer when the desktop toggle
is clicked. Restore desktop collapse/expand, preserve mobile navigation,
and close the drawer when resizing back to desktop.

Load the workaround only for known affected versions and script hashes,
so upgrades and changed bundles use upstream behavior automatically.

Verified desktop/mobile, keyboard and resize behavior, automatic disabling
with Book 1.2.0 and 1.4.0, and simulated same-version backports.

Diffstat:
MREADME | 8++++++++
A_exts/sidebar_toggle.py | 55+++++++++++++++++++++++++++++++++++++++++++++++++++++++
A_static/sidebar-toggle-fix.css | 6++++++
A_static/sidebar-toggle-fix.js | 49+++++++++++++++++++++++++++++++++++++++++++++++++
Mconf.py | 1+
5 files changed, 119 insertions(+), 0 deletions(-)

diff --git a/README b/README @@ -16,6 +16,14 @@ Then, do "make html" for HTML, "make texinfo" for Texinfo, etc. The output is in subdir ‘_build’. +The sidebar workaround in ‘_exts/sidebar_toggle.py’ loads its JavaScript and +CSS only for the exact affected Book/PyData script bundles. Updating or +backporting either theme's JavaScript automatically disables the workaround; +unknown bundles use the theme's own behavior. Do not add new bundle hashes +without reproducing the bug and checking desktop, mobile and resize behavior. +The extension and its two ‘_static/sidebar-toggle-fix.*’ files can be removed +once the documentation builders have upgraded their themes. + The build is reproducible: the dates that Sphinx stamps into the output (the date in the .TH line of a manpage, \date{} in LaTeX, <dc:date> in the EPUB, ...) are taken from the commit date of HEAD rather than from the clock, so diff --git a/_exts/sidebar_toggle.py b/_exts/sidebar_toggle.py @@ -0,0 +1,55 @@ +"""Enable the sidebar workaround only for the affected upstream assets.""" + +import hashlib +from importlib import import_module +from pathlib import Path + + +# Exact affected bundles: Book 1.1.3/1.1.4 and PyData 0.16.1, including the +# distribution build served by docs.taler.net. An upstream update or +# distributor backport changes these hashes and disables BOTH workaround files, +# even if the package version stays the same. +# https://github.com/executablebooks/sphinx-book-theme/issues/865 +_AFFECTED_SCRIPTS = { + "sphinx_book_theme": ( + {"1.1.3", "1.1.4"}, + "sphinx-book-theme.js", + {"2a8659f18c2652c150f637144de5459d84d6212b1b4b591bf99ba3a6923f08f1"}, + ), + "pydata_sphinx_theme": ( + {"0.16.1"}, + "pydata-sphinx-theme.js", + { + "a4d0b4f65b7650a66f8b1c2fadd150055b26faad9e5aab98fe5fff1c726742eb", + "f264bd85cd58f330ce33afffc7839c247a93498680ab7968d7d2d1ddecf955fe", + }, + ), +} + + +def _add_workaround(app): + if app.builder.format != "html" or app.config.html_theme != "sphinx_book_theme": + return + + for module_name, (versions, filename, affected_hashes) in _AFFECTED_SCRIPTS.items(): + module = import_module(module_name) + if getattr(module, "__version__", None) not in versions: + return + script = ( + Path(module.__file__).parent / "theme" / module_name + / "static" / "scripts" / filename + ) + try: + digest = hashlib.sha256(script.read_bytes()).hexdigest() + except OSError: + return + if digest not in affected_hashes: + return + + app.add_css_file("sidebar-toggle-fix.css") + app.add_js_file("sidebar-toggle-fix.js") + + +def setup(app): + app.connect("builder-inited", _add_workaround) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/_static/sidebar-toggle-fix.css b/_static/sidebar-toggle-fix.css @@ -0,0 +1,6 @@ +/* Loaded only for the affected theme bundles by _exts/sidebar_toggle.py. */ +@media (min-width: 960px) { + body.taler-primary-sidebar-collapsed #pst-primary-sidebar { + display: none; + } +} diff --git a/_static/sidebar-toggle-fix.js b/_static/sidebar-toggle-fix.js @@ -0,0 +1,49 @@ +/* Loaded only for the affected theme bundles by _exts/sidebar_toggle.py. */ +document.addEventListener("DOMContentLoaded", () => { + const sidebar = document.getElementById("pst-primary-sidebar"); + const drawer = document.getElementById("pst-primary-sidebar-modal"); + const buttons = document.querySelectorAll(".primary-toggle"); + + // Leave unfamiliar layouts and the older checkbox-based theme alone. + if (!sidebar || !drawer || drawer.tagName !== "DIALOG" || buttons.length !== 1) { + return; + } + + const button = buttons[0]; + const desktop = window.matchMedia("(min-width: 960px)"); + const collapsedClass = "taler-primary-sidebar-collapsed"; + + function updateControls() { + const expanded = desktop.matches + ? !document.body.classList.contains(collapsedClass) + : drawer.open; + button.setAttribute("aria-expanded", String(expanded)); + button.setAttribute("aria-controls", desktop.matches ? sidebar.id : drawer.id); + } + + // Intercept desktop clicks before the theme's mobile drawer handler. + document.addEventListener("click", (event) => { + if (!desktop.matches || !button.contains(event.target)) { + return; + } + event.preventDefault(); + event.stopPropagation(); + document.body.classList.toggle(collapsedClass); + updateControls(); + }, true); + + desktop.addEventListener("change", () => { + // Let the theme restore the navigation to its desktop container. + if (desktop.matches && drawer.open) { + drawer.close(); + } + updateControls(); + }); + + // Opening, Escape and backdrop dismissal remain handled by the theme. + new MutationObserver(updateControls).observe(drawer, { + attributes: true, + attributeFilter: ["open"], + }); + updateControls(); +}); diff --git a/conf.py b/conf.py @@ -55,6 +55,7 @@ needs_sphinx = "8.0.0" extensions = [ "ebicsdomain", "typescriptdomain", + "sidebar_toggle", "sphinx.ext.todo", "sphinx.ext.graphviz", "sphinx.ext.imgmath",