or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-setup.mddirectives-nodes.mdheader-buttons.mdindex.mdpage-enhancement.mdtransforms.md
tile.json

tessl/pypi-sphinx-book-theme

A clean book theme for scientific explanations and documentation with Sphinx

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinx-book-theme@1.1.x

To install, run

npx @tessl/cli install tessl/pypi-sphinx-book-theme@1.1.0

index.mddocs/

Sphinx Book Theme

A lightweight Sphinx theme designed to create interactive book-like documentation websites. Built on Bootstrap 5, it provides flexible content layouts inspired by beautiful online books, specialized visual classes for Jupyter Notebooks, and launch buttons for connecting documentation to online interactive environments like BinderHub.

Package Information

  • Package Name: sphinx-book-theme
  • Package Type: pypi
  • Language: Python
  • Installation: pip install sphinx-book-theme
  • Dependencies: sphinx>=6.1, pydata-sphinx-theme==0.15.4

Core Imports

import sphinx_book_theme

For accessing specific components:

from sphinx_book_theme import get_html_theme_path, setup
from sphinx_book_theme.directives import Margin
from sphinx_book_theme.nodes import SideNoteNode, visit_SideNoteNode, depart_SideNoteNode
from sphinx_book_theme.header_buttons import (
    prep_header_buttons, add_header_buttons, update_sourcename,
    update_context_with_repository_info, as_bool, get_repo_parts, get_repo_url
)
from sphinx_book_theme.header_buttons.launch import add_launch_buttons
from sphinx_book_theme.header_buttons.source import add_source_buttons
from sphinx_book_theme._transforms import HandleFootnoteTransform
from sphinx_book_theme._compat import findall

Basic Usage

Add the theme to your Sphinx configuration in conf.py:

# Basic theme configuration
html_theme = "sphinx_book_theme"

# Optional theme customization
html_theme_options = {
    "repository_url": "https://github.com/username/repo",
    "use_download_button": True,
    "use_fullscreen_button": True,
    "launch_buttons": {
        "binderhub_url": "https://mybinder.org",
        "thebe": True
    }
}

For programmatic access to theme functionality:

from sphinx.application import Sphinx
import sphinx_book_theme

# Get theme path
theme_path = sphinx_book_theme.get_html_theme_path()

# Setup theme in Sphinx application
app = Sphinx(...)
sphinx_book_theme.setup(app)

Architecture

The sphinx-book-theme extends the pydata-sphinx-theme with book-specific features:

  • Theme System: HTML templates, CSS, and JavaScript assets for book-style presentation
  • Sphinx Extension: Registers as a Sphinx extension with event handlers and configuration
  • Interactive Elements: Header buttons for downloads, launches, and source navigation
  • Content Enhancement: Custom directives (margin notes) and nodes (sidenotes)
  • Transform Pipeline: Post-processing to convert footnotes to margin/side notes

Capabilities

Core Theme Setup

Main Sphinx extension registration, theme path resolution, and core setup functionality. Includes the primary setup() function that registers the theme with Sphinx.

def setup(app: Sphinx) -> dict
def get_html_theme_path() -> Path

Core Theme Setup

Page Enhancement and Context

Functions that enhance page rendering with metadata, asset hashing, and template processing for improved performance and functionality.

def add_metadata_to_page(app, pagename, templatename, context, doctree)
def hash_html_assets(app, pagename, templatename, context, doctree)
def update_templates(app, pagename, templatename, context, doctree)

Page Enhancement

Directives and Custom Nodes

Custom reStructuredText directives and docutils nodes for enhanced content presentation, including margin notes and side notes.

class Margin(Sidebar)
class SideNoteNode(nodes.Element)

Directives and Nodes

Header Buttons System

Interactive header button functionality including download buttons, launch buttons for online environments (Binder, JupyterHub, Colab), and source repository navigation.

def add_header_buttons(app, pagename, templatename, context, doctree)
def add_launch_buttons(app, pagename, templatename, context, doctree)
def add_source_buttons(app, pagename, templatename, context, doctree)

Header Buttons

Content Transforms

Post-processing transforms that modify document structure, particularly for converting footnotes to margin/side notes.

class HandleFootnoteTransform(SphinxPostTransform)

Content Transforms

Configuration and Theming

Theme configuration functions, deprecation checks, and Thebe integration for interactive code execution.

def update_mode_thebe_config(app)
def check_deprecation_keys(app)
def update_general_config(app, config)

Configuration

Types

# Sphinx application type
from sphinx.application import Sphinx

# Path handling
from pathlib import Path

# Docutils node types
from docutils import nodes
from docutils.nodes import Element, document

# Optional type annotations
from typing import Any, Optional, Iterator