0
# Sphinx Book Theme
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: sphinx-book-theme
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install sphinx-book-theme`
10
- **Dependencies**: `sphinx>=6.1`, `pydata-sphinx-theme==0.15.4`
11

12
## Core Imports
13

14
```python
15
import sphinx_book_theme
16
```
17

18
For accessing specific components:
19

20
```python
21
from sphinx_book_theme import get_html_theme_path, setup
22
from sphinx_book_theme.directives import Margin
23
from sphinx_book_theme.nodes import SideNoteNode, visit_SideNoteNode, depart_SideNoteNode
24
from sphinx_book_theme.header_buttons import (
25
    prep_header_buttons, add_header_buttons, update_sourcename,
26
    update_context_with_repository_info, as_bool, get_repo_parts, get_repo_url
27
)
28
from sphinx_book_theme.header_buttons.launch import add_launch_buttons
29
from sphinx_book_theme.header_buttons.source import add_source_buttons
30
from sphinx_book_theme._transforms import HandleFootnoteTransform
31
from sphinx_book_theme._compat import findall
32
```
33

34
## Basic Usage
35

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

38
```python
39
# Basic theme configuration
40
html_theme = "sphinx_book_theme"
41

42
# Optional theme customization
43
html_theme_options = {
44
    "repository_url": "https://github.com/username/repo",
45
    "use_download_button": True,
46
    "use_fullscreen_button": True,
47
    "launch_buttons": {
48
        "binderhub_url": "https://mybinder.org",
49
        "thebe": True
50
    }
51
}
52
```
53

54
For programmatic access to theme functionality:
55

56
```python
57
from sphinx.application import Sphinx
58
import sphinx_book_theme
59

60
# Get theme path
61
theme_path = sphinx_book_theme.get_html_theme_path()
62

63
# Setup theme in Sphinx application
64
app = Sphinx(...)
65
sphinx_book_theme.setup(app)
66
```
67

68
## Architecture
69

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

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

78
## Capabilities
79

80
### Core Theme Setup
81

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

84
```python { .api }
85
def setup(app: Sphinx) -> dict
86
def get_html_theme_path() -> Path
87
```
88

89
[Core Theme Setup](./core-setup.md)
90

91
### Page Enhancement and Context
92

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

95
```python { .api }
96
def add_metadata_to_page(app, pagename, templatename, context, doctree)
97
def hash_html_assets(app, pagename, templatename, context, doctree)
98
def update_templates(app, pagename, templatename, context, doctree)
99
```
100

101
[Page Enhancement](./page-enhancement.md)
102

103
### Directives and Custom Nodes
104

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

107
```python { .api }
108
class Margin(Sidebar)
109
class SideNoteNode(nodes.Element)
110
```
111

112
[Directives and Nodes](./directives-nodes.md)
113

114
### Header Buttons System
115

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

118
```python { .api }
119
def add_header_buttons(app, pagename, templatename, context, doctree)
120
def add_launch_buttons(app, pagename, templatename, context, doctree)
121
def add_source_buttons(app, pagename, templatename, context, doctree)
122
```
123

124
[Header Buttons](./header-buttons.md)
125

126
### Content Transforms
127

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

130
```python { .api }
131
class HandleFootnoteTransform(SphinxPostTransform)
132
```
133

134
[Content Transforms](./transforms.md)
135

136
### Configuration and Theming
137

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

140
```python { .api }
141
def update_mode_thebe_config(app)
142
def check_deprecation_keys(app)
143
def update_general_config(app, config)
144
```
145

146
[Configuration](./configuration.md)
147

148
## Types
149

150
```python { .api }
151
# Sphinx application type
152
from sphinx.application import Sphinx
153

154
# Path handling
155
from pathlib import Path
156

157
# Docutils node types
158
from docutils import nodes
159
from docutils.nodes import Element, document
160

161
# Optional type annotations
162
from typing import Any, Optional, Iterator
163
```