0
# Header Buttons System
1
2
Interactive header button functionality for downloads, online launches, and source repository navigation. Provides integration with services like Binder, JupyterHub, Colab, and source control platforms.
3
4
## Capabilities
5
6
### Header Button Management
7
8
Core functions for managing and adding header buttons to pages.
9
10
```python { .api }
11
def prep_header_buttons(app, pagename, templatename, context, doctree):
12
"""
13
Initialize empty header buttons list in page context.
14
15
Sets up context["header_buttons"] = [] for other functions to populate.
16
17
Parameters:
18
- app: Sphinx application instance
19
- pagename: Name of the page being processed
20
- templatename: Template being used
21
- context: Template context (modified to include header_buttons list)
22
- doctree: Document tree for the page
23
"""
24
25
def add_header_buttons(app, pagename, templatename, context, doctree):
26
"""
27
Add general header buttons including download and fullscreen buttons.
28
29
Adds buttons for:
30
- Download source file (.rst, .md, .ipynb)
31
- Download as PDF (print to PDF)
32
- Fullscreen mode toggle
33
34
Parameters:
35
- app: Sphinx application instance
36
- pagename: Name of the page being processed
37
- templatename: Template being used
38
- context: Template context with header_buttons list
39
- doctree: Document tree for the page
40
"""
41
```
42
43
### Launch Button Integration
44
45
Functions for adding launch buttons that connect to online interactive environments.
46
47
```python { .api }
48
def add_launch_buttons(app: Sphinx, pagename: str, templatename: str,
49
context: dict[str, Any], doctree: Optional[document]):
50
"""
51
Add launch buttons for interactive online environments.
52
53
Supports:
54
- Binder (BinderHub instances)
55
- JupyterHub
56
- Google Colab
57
- Deepnote
58
- Thebe (live code execution)
59
60
Parameters:
61
- app: Sphinx application instance
62
- pagename: Name of the page being processed
63
- templatename: Template being used
64
- context: Template context with header_buttons and launch configuration
65
- doctree: Document tree (optional, None for HTML-only pages)
66
"""
67
```
68
69
### Source Repository Buttons
70
71
Functions for adding buttons that link to source repository features.
72
73
```python { .api }
74
def add_source_buttons(app, pagename, templatename, context, doctree):
75
"""
76
Add source repository navigation buttons.
77
78
Provides buttons for:
79
- Repository home page
80
- View source file online
81
- Edit page (suggest edit)
82
- Open issue/bug report
83
84
Supports GitHub, GitLab, and Bitbucket.
85
86
Parameters:
87
- app: Sphinx application instance
88
- pagename: Name of the page being processed
89
- templatename: Template being used
90
- context: Template context with repository configuration
91
- doctree: Document tree for the page
92
"""
93
```
94
95
### Repository Configuration
96
97
Functions for processing repository information and updating Sphinx configuration.
98
99
```python { .api }
100
def update_context_with_repository_info(app):
101
"""
102
Update Sphinx context with repository information from theme options.
103
104
Extracts repository URL, branch, and provider information from
105
theme configuration and populates html_context for use by
106
pydata-sphinx-theme functions.
107
108
Parameters:
109
- app: Sphinx application instance (config modified in-place)
110
"""
111
112
def update_sourcename(app):
113
"""
114
Configure source file suffix for download links.
115
116
Sets html_sourcelink_suffix to empty string unless explicitly
117
configured, ensuring native file extensions (.rst, .md) are used
118
instead of Sphinx's default .txt.
119
120
Parameters:
121
- app: Sphinx application instance (config modified in-place)
122
"""
123
```
124
125
### Utility Functions
126
127
Helper functions for processing configuration and repository information.
128
129
```python { .api }
130
def as_bool(var) -> bool:
131
"""
132
Convert various inputs to boolean values.
133
134
Handles string 'true'/'false', boolean values, and None.
135
136
Parameters:
137
- var: Value to convert (str, bool, or None)
138
139
Returns:
140
Boolean representation of the input
141
"""
142
143
def get_repo_parts(context) -> tuple:
144
"""
145
Extract repository components from page context.
146
147
Parameters:
148
- context: Page template context
149
150
Returns:
151
Tuple of (provider_url, user, repo, provider) or None if not found
152
"""
153
154
def get_repo_url(context) -> tuple[str, str]:
155
"""
156
Get complete repository URL and provider from context.
157
158
Parameters:
159
- context: Page template context
160
161
Returns:
162
Tuple of (repository_url, provider_name)
163
"""
164
165
def _split_repo_url(url) -> tuple:
166
"""
167
Split a repository URL into an org/repo combination.
168
169
Currently supports GitHub URLs, with warnings for other providers.
170
171
Parameters:
172
- url: Repository URL string
173
174
Returns:
175
Tuple of (org, repo) or (None, None) if not supported
176
"""
177
178
def _is_notebook(app, context) -> bool:
179
"""
180
Determine if the current page is a notebook.
181
182
Checks for 'kernelspec' in metadata or '.ipynb' in page source suffix.
183
184
Parameters:
185
- app: Sphinx application instance
186
- context: Page template context
187
188
Returns:
189
True if the page is a notebook, False otherwise
190
"""
191
192
def _get_branch(config_theme) -> str:
193
"""
194
Get repository branch from theme configuration.
195
196
Parameters:
197
- config_theme: Theme configuration dictionary
198
199
Returns:
200
Branch name (defaults to 'master' if not specified)
201
"""
202
```
203
204
### Module Constants
205
206
```python { .api }
207
# Launch module constants
208
SPHINX_LOGGER: Logger # Logger instance for launch button functionality
209
MESSAGE_CATALOG_NAME: str = "booktheme" # Translation catalog name
210
211
# Header buttons module constants
212
LOGGER: Logger # Logger instance for general header button functionality
213
```
214
215
## Usage Examples
216
217
### Basic Header Button Setup
218
219
```python
220
from sphinx_book_theme.header_buttons import prep_header_buttons, add_header_buttons
221
222
# In Sphinx conf.py
223
html_theme_options = {
224
"use_download_button": True,
225
"use_fullscreen_button": True,
226
}
227
228
# Buttons are automatically added via event handlers:
229
# app.connect("html-page-context", prep_header_buttons)
230
# app.connect("html-page-context", add_header_buttons, priority=501)
231
```
232
233
### Launch Button Configuration
234
235
```python
236
# In Sphinx conf.py
237
html_theme_options = {
238
"repository_url": "https://github.com/user/repo",
239
"repository_branch": "main",
240
"launch_buttons": {
241
"binderhub_url": "https://mybinder.org",
242
"jupyterhub_url": "https://hub.example.com",
243
"colab_url": "https://colab.research.google.com",
244
"thebe": True,
245
"notebook_interface": "jupyterlab" # or "classic"
246
}
247
}
248
```
249
250
### Source Button Configuration
251
252
```python
253
# In Sphinx conf.py
254
html_theme_options = {
255
"repository_url": "https://github.com/user/repo",
256
"use_repository_button": True,
257
"use_source_button": True,
258
"use_edit_page_button": True,
259
"use_issues_button": True,
260
"path_to_docs": "docs" # relative path to docs in repo
261
}
262
```
263
264
### Manual Button Addition
265
266
```python
267
from sphinx_book_theme.header_buttons import add_launch_buttons
268
269
def custom_page_handler(app, pagename, templatename, context, doctree):
270
# Ensure header_buttons exists
271
if "header_buttons" not in context:
272
context["header_buttons"] = []
273
274
# Add launch buttons if this is a notebook page
275
add_launch_buttons(app, pagename, templatename, context, doctree)
276
277
# Add custom button
278
context["header_buttons"].append({
279
"type": "link",
280
"url": "https://example.com",
281
"text": "Custom Link",
282
"tooltip": "Custom tooltip",
283
"icon": "fas fa-external-link-alt"
284
})
285
```
286
287
### Repository Information Processing
288
289
```python
290
from sphinx_book_theme.header_buttons import get_repo_parts, get_repo_url
291
292
# Extract repository information
293
context = {
294
"github_url": "https://github.com",
295
"github_user": "executablebooks",
296
"github_repo": "sphinx-book-theme"
297
}
298
299
# Get repository parts
300
provider_url, user, repo, provider = get_repo_parts(context)
301
# Returns: ("https://github.com", "executablebooks", "sphinx-book-theme", "github")
302
303
# Get full repository URL
304
repo_url, provider = get_repo_url(context)
305
# Returns: ("https://github.com/executablebooks/sphinx-book-theme", "github")
306
```