0
# Configuration and Theming
1

2
Theme configuration functions, deprecation handling, and integration with interactive code execution systems like Thebe.
3

4
## Capabilities
5

6
### Thebe Integration
7

8
Configuration functions for integrating with Thebe for live code execution in documentation.
9

10
```python { .api }
11
def update_mode_thebe_config(app):
12
    """
13
    Update Thebe configuration with sphinx-book-theme specific values.
14
    
15
    Automatically configures Thebe when launch_buttons.thebe is enabled:
16
    - Sets repository_url if not already configured
17
    - Sets repository_branch (defaults to 'master' if not specified)
18
    - Warns if sphinx_thebe extension is not installed
19
    
20
    Parameters:
21
    - app: Sphinx application instance (thebe_config modified in-place)
22
    """
23
```
24

25
### Configuration Management
26

27
Functions for managing theme configuration and handling deprecated options.
28

29
```python { .api }
30
def check_deprecation_keys(app):
31
    """
32
    Check for and warn about deprecated configuration keys.
33
    
34
    Currently checks for:
35
    - 'single_page': Deprecated since version 0.3.4
36
    
37
    Issues warnings with links to changelog for deprecated options.
38
    
39
    Parameters:
40
    - app: Sphinx application instance
41
    """
42

43
def update_general_config(app, config):
44
    """
45
    Update general Sphinx configuration for the theme.
46
    
47
    Adds theme template paths to Sphinx configuration:
48
    - Adds theme/components directory to templates_path
49
    
50
    Parameters:
51
    - app: Sphinx application instance
52
    - config: Sphinx configuration object (modified in-place)
53
    """
54
```
55

56
### Translation Support
57

58
Functions for internationalization and message catalog management.
59

60
```python { .api }
61
# Translation constants
62
MESSAGE_CATALOG_NAME: str = "booktheme"  # Catalog identifier
63

64
# Translation setup is handled in setup() function:
65
# - Adds message catalog from theme/static/locales
66
# - Provides translation context in page rendering
67
```
68

69
## Usage Examples
70

71
### Thebe Configuration
72

73
```python
74
# In Sphinx conf.py
75
extensions = ['sphinx_thebe']  # Required for Thebe support
76

77
html_theme_options = {
78
    "repository_url": "https://github.com/user/repo",
79
    "repository_branch": "main",
80
    "launch_buttons": {
81
        "thebe": True
82
    }
83
}
84

85
# Optional custom Thebe configuration
86
thebe_config = {
87
    "repository_url": "https://github.com/user/repo",
88
    "repository_branch": "main", 
89
    "repository_provider": "github",
90
    "selector": ".cell",
91
    "kernel_name": "python3"
92
}
93
```
94

95
### Deprecation Handling
96

97
```python
98
# Configuration that triggers deprecation warning
99
html_theme_options = {
100
    "single_page": True,  # Will generate warning
101
    "use_download_button": True  # Valid option
102
}
103

104
# Warning output:
105
# WARNING: 'single_page' was deprecated from version 0.3.4 onwards.
106
# See the CHANGELOG for more information: 
107
# https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md
108
```
109

110
### Custom Configuration Processing
111

112
```python
113
from sphinx_book_theme import check_deprecation_keys, update_general_config
114

115
def setup(app):
116
    # Check for deprecated options during builder initialization
117
    app.connect("builder-inited", check_deprecation_keys)
118
    
119
    # Update configuration
120
    update_general_config(app, app.config)
121
    
122
    return {"parallel_read_safe": True}
123
```
124

125
### Manual Thebe Setup
126

127
```python
128
from sphinx_book_theme import update_mode_thebe_config
129
from pydata_sphinx_theme.utils import get_theme_options_dict
130

131
def custom_thebe_setup(app):
132
    # Configure theme options first
133
    theme_options = get_theme_options_dict(app)
134
    theme_options["launch_buttons"] = {"thebe": True}
135
    theme_options["repository_url"] = "https://github.com/user/repo"
136
    
137
    # Update Thebe configuration
138
    update_mode_thebe_config(app)
139
    
140
    # Check resulting configuration
141
    if hasattr(app.env.config, 'thebe_config'):
142
        thebe_config = app.env.config.thebe_config
143
        print(f"Thebe repository: {thebe_config.get('repository_url')}")
144
        print(f"Thebe branch: {thebe_config.get('repository_branch')}")
145
```
146

147
### Translation Context
148

149
```python
150
from sphinx.locale import get_translation
151

152
# Get translation function (done automatically in page context)
153
translation = get_translation("booktheme")
154

155
# Use in templates or code
156
translated_text = translation("Download this page")
157
search_placeholder = translation("Search") + "..."
158
```
159

160
## Configuration Options
161

162
### Theme Options
163

164
```python
165
html_theme_options = {
166
    # Launch buttons
167
    "launch_buttons": {
168
        "thebe": True,
169
        "binderhub_url": "https://mybinder.org",
170
        "jupyterhub_url": "https://hub.example.com",
171
        "colab_url": "https://colab.research.google.com",
172
        "notebook_interface": "jupyterlab"  # or "classic"
173
    },
174
    
175
    # Repository configuration  
176
    "repository_url": "https://github.com/user/repo",
177
    "repository_branch": "main",
178
    "repository_provider": "github",  # auto-detected if not specified
179
    "path_to_docs": "docs",
180
    
181
    # Button toggles
182
    "use_download_button": True,
183
    "use_fullscreen_button": True, 
184
    "use_repository_button": True,
185
    "use_source_button": True,
186
    "use_edit_page_button": True,
187
    "use_issues_button": True,
188
    
189
    # Content features
190
    "use_sidenotes": True,
191
    
192
    # Footer customization
193
    "theme_footer_content_items": ["copyright", "sphinx-version"],
194
    
195
    # Search
196
    "search_bar_text": "Search documentation..."
197
}
198
```
199

200
### Thebe-specific Configuration
201

202
```python
203
# Additional Thebe configuration
204
thebe_config = {
205
    "repository_url": "https://github.com/user/repo",
206
    "repository_branch": "main",
207
    "repository_provider": "github",
208
    "selector": "div.highlight",  # Elements to make executable
209
    "kernel_name": "python3",
210
    "request_kernel_on_load": False,
211
    "pre_render_hook": "function() { console.log('Pre-render'); }",
212
    "mount_hook": "function() { console.log('Mounted'); }"
213
}
214
```
215

216
### Event Handler Registration
217

218
```python
219
def setup(app):
220
    # Configuration events
221
    app.connect("builder-inited", update_mode_thebe_config)
222
    app.connect("builder-inited", check_deprecation_keys) 
223
    app.connect("config-inited", update_general_config)
224
    
225
    return {"parallel_read_safe": True}
226
```