0
# HTML Translation
1
2
Bootstrap-specific HTML translator that modifies Sphinx's default HTML output to be compatible with Bootstrap 5 styling, including table formatting and accessibility improvements.
3
4
## Capabilities
5
6
### Bootstrap HTML Translator
7
8
Mixin class that enhances Sphinx's HTML output for Bootstrap compatibility.
9
10
```python { .api }
11
class BootstrapHTML5TranslatorMixin:
12
"""
13
Mixin HTML Translator for a Bootstrap-ified Sphinx layout.
14
15
Modifies Sphinx's default HTML output to produce valid HTML that can be
16
directly styled with Bootstrap, while fulfilling accessibility best practices.
17
Only overrides specific functions needed for Bootstrap compatibility.
18
19
This mixin is combined with Sphinx's existing translators to retain all
20
original functionality while adding Bootstrap-specific enhancements.
21
"""
22
23
def __init__(self, *args, **kwds):
24
"""
25
Initialize the translator with Bootstrap table styling.
26
27
Sets default table style to 'table' for Bootstrap compatibility.
28
29
Parameters:
30
- *args: Arguments passed to parent translator
31
- **kwds: Keyword arguments passed to parent translator
32
"""
33
34
def starttag(self, *args, **kwargs):
35
"""
36
Perform small modifications to tags.
37
38
Ensures accessibility compliance by:
39
- Setting aria-level for any tag with heading role
40
- Maintaining all original starttag functionality
41
42
Parameters:
43
- *args: Arguments for tag creation
44
- **kwargs: Tag attributes and options
45
46
Returns:
47
str: HTML start tag with Bootstrap and accessibility enhancements
48
"""
49
50
def visit_table(self, node):
51
"""
52
Custom visit table method.
53
54
Creates Bootstrap-compatible tables by:
55
- Adding 'table' class instead of 'docutils' and 'align-default'
56
- Supporting autosummary tables with special styling
57
- Adding responsive table wrapper for horizontal scrolling
58
- Preserving width and alignment attributes
59
60
Parameters:
61
- node: Table node being processed
62
"""
63
64
def depart_table(self, node):
65
"""
66
Custom depart_table method to close the scrollable div.
67
68
Properly closes the scrollable container div added in visit_table
69
while maintaining parent functionality.
70
71
Parameters:
72
- node: Table node being processed
73
"""
74
```
75
76
### Translator Setup
77
78
Configures Bootstrap HTML functionality for Sphinx builders.
79
80
```python { .api }
81
def setup_translators(app: Sphinx):
82
"""
83
Add bootstrap HTML functionality if we are using an HTML translator.
84
85
Dynamically creates new translator classes that combine the Bootstrap
86
mixin with existing Sphinx translators. This preserves all original
87
translator behavior while adding Bootstrap-specific enhancements.
88
89
The function:
90
- Detects existing HTML translators
91
- Creates new classes combining Bootstrap mixin with original translators
92
- Registers the enhanced translators with Sphinx
93
- Skips non-HTML builders to avoid conflicts
94
95
Parameters:
96
- app (Sphinx): Sphinx application instance
97
"""
98
```
99
100
## Table Styling
101
102
### Bootstrap Table Classes
103
104
The translator automatically applies Bootstrap table classes:
105
106
```html
107
<!-- Standard Sphinx table -->
108
<table class="docutils align-default">
109
<thead>...</thead>
110
<tbody>...</tbody>
111
</table>
112
113
<!-- Bootstrap-enhanced table -->
114
<div class="pst-scrollable-table-container">
115
<table class="table">
116
<thead>...</thead>
117
<tbody>...</tbody>
118
</table>
119
</div>
120
```
121
122
### Table Alignment Support
123
124
```rst
125
.. table:: Aligned Table
126
:align: center
127
128
====== ======
129
Header Header
130
====== ======
131
Data Data
132
====== ======
133
```
134
135
Results in:
136
```html
137
<div class="pst-scrollable-table-container">
138
<table class="table table-center">
139
<!-- table content -->
140
</table>
141
</div>
142
```
143
144
### Responsive Table Wrapper
145
146
All tables are wrapped in a scrollable container for mobile responsiveness:
147
148
```css
149
.pst-scrollable-table-container {
150
overflow-x: auto;
151
-webkit-overflow-scrolling: touch;
152
}
153
```
154
155
## Accessibility Enhancements
156
157
### Heading Role Attributes
158
159
The translator ensures proper accessibility for heading elements:
160
161
```html
162
<!-- Automatic aria-level addition -->
163
<div role="heading" aria-level="2">Section Title</div>
164
```
165
166
### Table Accessibility
167
168
Bootstrap table styling maintains accessibility features:
169
- Proper table structure with `<thead>` and `<tbody>`
170
- Semantic HTML5 elements
171
- Screen reader compatibility
172
173
## Autosummary Integration
174
175
Special handling for Sphinx autosummary tables:
176
177
```python
178
# When sphinx.ext.autosummary generates API tables
179
# The translator adds 'autosummary' class automatically
180
```
181
182
Results in:
183
```html
184
<div class="pst-scrollable-table-container">
185
<table class="table autosummary">
186
<!-- API documentation table -->
187
</table>
188
</div>
189
```
190
191
## Usage Examples
192
193
### Basic Table Styling
194
195
```rst
196
Simple Table
197
============
198
199
====== ====== ======
200
Col 1 Col 2 Col 3
201
====== ====== ======
202
Data Data Data
203
More More More
204
====== ====== ======
205
```
206
207
### Wide Tables (Responsive)
208
209
```rst
210
Wide Data Table
211
===============
212
213
=========== =========== =========== =========== ===========
214
Parameter Type Default Description Example
215
=========== =========== =========== =========== ===========
216
width int 800 Table width 1200
217
height int 600 Table height 900
218
responsive bool True Enable wrap False
219
=========== =========== =========== =========== ===========
220
```
221
222
The wide table automatically gets horizontal scrolling on mobile devices.
223
224
### Custom Table Styling
225
226
```rst
227
.. table:: Custom Styled Table
228
:widths: 30 70
229
:width: 100%
230
231
========== ====================================
232
Feature Description
233
========== ====================================
234
Bootstrap Automatic Bootstrap 5 styling
235
Responsive Mobile-friendly horizontal scroll
236
Accessible ARIA attributes and semantic HTML
237
========== ====================================
238
```
239
240
## CSS Integration
241
242
The translator works with Bootstrap CSS classes:
243
244
```css
245
/* Bootstrap table styling is automatically applied */
246
.table {
247
width: 100%;
248
margin-bottom: 1rem;
249
color: var(--bs-body-color);
250
vertical-align: top;
251
border-color: var(--bs-border-color);
252
}
253
254
/* Theme-specific table enhancements */
255
.pst-scrollable-table-container {
256
overflow-x: auto;
257
margin-bottom: 1rem;
258
}
259
260
.table.autosummary {
261
font-size: 0.9em;
262
}
263
264
.table.autosummary td {
265
white-space: nowrap;
266
}
267
```
268
269
## Builder Compatibility
270
271
The translator setup detects and works with various Sphinx builders:
272
273
- **HTML builders**: Enhanced with Bootstrap functionality
274
- **Non-HTML builders**: Skipped to avoid conflicts (e.g., LaTeX, linkcheck)
275
- **Custom builders**: Automatic detection and compatibility
276
277
## Advanced Configuration
278
279
### Disable Bootstrap Tables
280
281
```python
282
# conf.py - Disable Bootstrap table enhancement
283
# (Advanced: requires custom theme modification)
284
def setup(app):
285
# Custom setup without Bootstrap translator
286
pass
287
```
288
289
### Custom Table Styles
290
291
```python
292
# conf.py - Custom table styling
293
html_theme_options = {
294
"custom_css": "custom-tables.css"
295
}
296
```
297
298
```css
299
/* custom-tables.css */
300
.table {
301
border-collapse: separate;
302
border-spacing: 0;
303
}
304
305
.table thead th {
306
border-bottom: 2px solid var(--pst-color-primary);
307
}
308
309
.table.autosummary {
310
font-family: 'Monaco', 'Menlo', monospace;
311
}
312
```
313
314
## Performance Considerations
315
316
- **Minimal overhead**: Only modifies table-related HTML generation
317
- **Selective enhancement**: Only affects HTML builders
318
- **Dynamic creation**: Translator classes created once during initialization
319
- **Preserved functionality**: All original Sphinx translator features retained
320
321
## Error Handling
322
323
The translator setup handles various scenarios:
324
325
- **No translators**: Uses builder's default translator class
326
- **Missing attributes**: Graceful fallback for builders without default_translator_class
327
- **Builder detection**: Automatically skips incompatible builders
328
329
## Integration with Extensions
330
331
The Bootstrap translator works with other Sphinx extensions:
332
333
### With sphinx.ext.autosummary
334
- Automatic detection and styling of API tables
335
- Special CSS classes for documentation tables
336
337
### With sphinx.ext.napoleon
338
- Proper table formatting for NumPy/Google style docstrings
339
- Enhanced parameter tables
340
341
### With custom extensions
342
- Compatible with any extension that generates tables
343
- Maintains all accessibility and responsive features