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
```