$ show executablebooks/sphinx-book-theme
Sphinx Book Theme is a Python package implementing a book-style HTML theme for Sphinx documentation builds. It extends pydata-sphinx-theme (pinned to 0.22.0) and adds custom docutils directives (Margin), a build-time transform that rewrites footnotes into Tufte-style side/margin notes, and header-button generators that emit launch links for Binder/Colab/JupyterHub/Deepnote/JupyterLite plus source links for GitHub/GitLab/Bitbucket. It is distributed on PyPI and serves as the default theme for Jupyter Book, making it a foundational component of the scientific Python documentation ecosystem. Despite this research-communication role, it is a software library, not a data tool — it renders and styles documentation rather than analyzing data. This hybrid character is worth noting: the repo does not contain data pipelines, notebooks for analysis, or research outputs; it contains a Sphinx plugin and frontend asset pipeline. The Python layer is thin but carefully engineered. Theme setup in __init__.py registers Sphinx events, directives, nodes, and transforms; header_buttons/ uses a clean per-provider functional abstraction for generating URLs; _compat.py guards against docutils API drift; and _compile_translations.py coordinates a JSON-to-PO/MO translation workflow. The frontend is compiled with Webpack from a 7-1-architecture SCSS codebase with sections for layout, content, and third-party extension overrides. Tests build real sample sites and use pytest-regressions to verify rendered HTML across Python 3.11-3.14 and Sphinx 8-9, which demonstrates solid engineering discipline for a theme project. The README explicitly declares maintenance mode: bug fixes only, no new features. The last commit is recent and CI runs continuously, but the tightly pinned pydata-sphinx-theme dependency, Sphinx 11 deprecation warnings in the test config, and hand-maintained translation files indicate slow technical drift. For engineers looking for reusable pieces, the standout items are the footnote-to-sidenote transform, the header-button provider pattern, and the HTML asset-hashing utility; the Jinja templates and SCSS are heavily theme-specific and not worth extracting.
The LLM identified 4 files worth highlighting for reuse:
HandleFootnoteTransform hooks into the Sphinx/docutils build and rewrites footnote references into Tufte-style side/margin notes based on theme configuration. This is non-obvious docutils transformer work — manipulating the doctree at build time to change typography semantics. The transform is isolated from theme rendering internals and could be ported to other Sphinx themes with minimal adaptation, making it a genuinely reusable component rather than theme boilerplate.
Generates launch URLs for Binder, Colab, JupyterHub, Deepnote, and JupyterLite from Sphinx configuration. Each provider is implemented as a clean, self-contained pure function mapping config values to a URL string. The provider-registry-plus-config pattern is abstrable beyond this theme and demonstrates good functional design: no shared state, no tight coupling to rendering internals, and easy to test in isolation.
The theme setup module registers Sphinx events, directives, and header-button hooks. Its hash_html_assets utility appends digest query strings to CSS/JS URLs for cache invalidation — a small but genuinely reusable helper for any Sphinx sub-theme, showing non-obvious knowledge of how Sphinx computes static asset paths and how to version them without a CDN or build-hash ceremony.
A thin compatibility shim providing docutils findall across version differences. Small in size but demonstrates the right pattern for deprecation-proofing a library against upstream API churn: centralize version detection, expose a stable internal API, and avoid scattering conditional imports through the codebase. Directly reusable in any docutils-based project facing the same migration.