0
# Tweaks and Enhancements
1

2
Small but important improvements to Sphinx functionality including tab size handling, parameter formatting, footnote symbols, and compatibility fixes. These tweaks address common pain points and enhance the user experience with subtle but valuable improvements to Sphinx's default behavior.
3

4
## Capabilities
5

6
### Tab Size Handling
7

8
Enhanced tab width processing for code blocks and documentation with configurable tab size detection and conversion.
9

10
```python { .api }
11
def setup_tabsize_support(app: Sphinx) -> None:
12
    """
13
    Set up enhanced tab size handling for code blocks.
14
    
15
    Args:
16
        app: Sphinx application instance
17
    """
18

19
def get_tab_width(app: Sphinx, docname: str) -> int:
20
    """
21
    Get effective tab width for a document.
22
    
23
    Args:
24
        app: Sphinx application instance
25
        docname: Document name
26
        
27
    Returns:
28
        Tab width in spaces
29
    """
30

31
def convert_tabs_to_spaces(content: str, tab_width: int = 8) -> str:
32
    """
33
    Convert tabs to spaces in content.
34
    
35
    Args:
36
        content: Content with potential tabs
37
        tab_width: Number of spaces per tab
38
        
39
    Returns:
40
        Content with tabs converted to spaces
41
    """
42

43
class TabSizeProcessor:
44
    """Processor for handling tab size in documents."""
45
    
46
    def __init__(self, tab_width: int = 8) -> None:
47
        """
48
        Initialize tab size processor.
49
        
50
        Args:
51
            tab_width: Default tab width in spaces
52
        """
53
        
54
    def process_code_block(self, content: List[str]) -> List[str]:
55
        """Process code block content for consistent tab handling."""
56
        
57
    def detect_tab_width(self, content: str) -> int:
58
        """Detect likely tab width from content indentation."""
59
```
60

61
### Parameter Dash Formatting
62

63
Enhanced parameter formatting in docstrings with proper dash handling and consistent formatting.
64

65
```python { .api }
66
def format_param_dash(param_line: str) -> str:
67
    """
68
    Format parameter line with proper dash handling.
69
    
70
    Args:
71
        param_line: Raw parameter line from docstring
72
        
73
    Returns:
74
        Formatted parameter line with consistent dashes
75
    """
76

77
def normalize_param_formatting(docstring: str) -> str:
78
    """
79
    Normalize parameter formatting throughout docstring.
80
    
81
    Args:
82
        docstring: Raw docstring text
83
        
84
    Returns:
85
        Docstring with normalized parameter formatting
86
    """
87

88
class ParameterFormatter:
89
    """Formatter for docstring parameters."""
90
    
91
    def __init__(self, dash_style: str = 'single') -> None:
92
        """
93
        Initialize parameter formatter.
94
        
95
        Args:
96
            dash_style: Style of dashes to use ('single', 'double', 'em')
97
        """
98
        
99
    def format_parameter_list(self, params: List[str]) -> List[str]:
100
        """Format list of parameter descriptions."""
101
        
102
    def format_returns_section(self, returns_text: str) -> str:
103
        """Format returns section with consistent styling."""
104
```
105

106
### Footnote Symbol Enhancements
107

108
Enhanced footnote handling with symbol support, custom numbering, and improved formatting.
109

110
```python { .api }
111
class FootnoteSymbols:
112
    """Enhanced footnote symbol handling."""
113
    
114
    SYMBOLS = ['*', '†', '‡', '§', '¶', '‖', '**', '††', '‡‡']
115
    
116
    def __init__(self, style: str = 'symbols') -> None:
117
        """
118
        Initialize footnote symbols.
119
        
120
        Args:
121
            style: Footnote style ('symbols', 'numbers', 'roman', 'alpha')
122
        """
123
        
124
    def get_footnote_symbol(self, index: int) -> str:
125
        """Get footnote symbol for given index."""
126
        
127
    def reset_counters(self) -> None:
128
        """Reset footnote counters."""
129

130
def setup_footnote_symbols(app: Sphinx, symbol_style: str = 'symbols') -> None:
131
    """
132
    Set up enhanced footnote symbol handling.
133
    
134
    Args:
135
        app: Sphinx application instance
136
        symbol_style: Style of footnote symbols to use
137
    """
138

139
def revert_footnote_style(app: Sphinx) -> None:
140
    """
141
    Revert to default Sphinx footnote styling.
142
    
143
    Args:
144
        app: Sphinx application instance
145
    """
146
```
147

148
### LaTeX Layout Improvements
149

150
Tweaks and enhancements for LaTeX output including spacing, headers, and formatting improvements.
151

152
```python { .api }
153
def configure_latex_tweaks(app: Sphinx) -> None:
154
    """
155
    Apply comprehensive LaTeX layout improvements.
156
    
157
    Args:
158
        app: Sphinx application instance
159
    """
160

161
def improve_latex_spacing(config: Config) -> None:
162
    """
163
    Improve LaTeX spacing throughout the document.
164
    
165
    Args:
166
        config: Sphinx configuration object
167
    """
168

169
def enhance_latex_headers(config: Config) -> None:
170
    """
171
    Enhance LaTeX header formatting and spacing.
172
    
173
    Args:
174
        config: Sphinx configuration object
175
    """
176

177
def fix_latex_toc_formatting(config: Config) -> None:
178
    """
179
    Fix table of contents formatting issues in LaTeX.
180
    
181
    Args:
182
        config: Sphinx configuration object
183
    """
184

185
class LaTeXLayoutTweaks:
186
    """Collection of LaTeX layout improvements."""
187
    
188
    def __init__(self, config: Config) -> None: ...
189
    
190
    def apply_spacing_tweaks(self) -> None:
191
        """Apply spacing improvements."""
192
        
193
    def apply_header_tweaks(self) -> None:
194
        """Apply header formatting improvements."""
195
        
196
    def apply_toc_tweaks(self) -> None:
197
        """Apply table of contents improvements."""
198
```
199

200
### Sphinx Panels Compatibility
201

202
Compatibility fixes and enhancements for sphinx-panels integration.
203

204
```python { .api }
205
def setup_sphinx_panels_compat(app: Sphinx) -> None:
206
    """
207
    Set up sphinx-panels compatibility tweaks.
208
    
209
    Args:
210
        app: Sphinx application instance
211
    """
212

213
def fix_panels_tabs_conflict(app: Sphinx) -> None:
214
    """
215
    Fix conflicts between sphinx-panels and other tab implementations.
216
    
217
    Args:
218
        app: Sphinx application instance
219
    """
220

221
class PanelsCompatibilityLayer:
222
    """Compatibility layer for sphinx-panels integration."""
223
    
224
    def __init__(self, app: Sphinx) -> None: ...
225
    
226
    def register_panels_nodes(self) -> None:
227
        """Register sphinx-panels nodes for compatibility."""
228
        
229
    def handle_panels_css(self) -> None:
230
        """Handle sphinx-panels CSS integration."""
231
```
232

233
### Code Block Enhancements
234

235
Minor but useful enhancements to code block processing and display.
236

237
```python { .api }
238
def enhance_code_blocks(app: Sphinx) -> None:
239
    """
240
    Apply code block enhancements.
241
    
242
    Args:
243
        app: Sphinx application instance
244
    """
245

246
def fix_code_block_indentation(content: str, base_indent: int = 0) -> str:
247
    """
248
    Fix code block indentation issues.
249
    
250
    Args:
251
        content: Code block content
252
        base_indent: Base indentation level
253
        
254
    Returns:
255
        Content with fixed indentation
256
    """
257

258
def normalize_line_endings(content: str) -> str:
259
    """
260
    Normalize line endings in code blocks.
261
    
262
    Args:
263
        content: Content with mixed line endings
264
        
265
    Returns:
266
        Content with normalized line endings
267
    """
268
```
269

270
### HTML Output Tweaks
271

272
Small improvements to HTML output for better appearance and functionality.
273

274
```python { .api }
275
def apply_html_tweaks(app: Sphinx) -> None:
276
    """
277
    Apply HTML output improvements.
278
    
279
    Args:
280
        app: Sphinx application instance
281
    """
282

283
def improve_html_tables(app: Sphinx) -> None:
284
    """
285
    Improve HTML table formatting and responsiveness.
286
    
287
    Args:
288
        app: Sphinx application instance
289
    """
290

291
def enhance_html_navigation(app: Sphinx) -> None:
292
    """
293
    Enhance HTML navigation elements.
294
    
295
    Args:
296
        app: Sphinx application instance
297
    """
298

299
class HTMLTweaks:
300
    """Collection of HTML output improvements."""
301
    
302
    def __init__(self, app: Sphinx) -> None: ...
303
    
304
    def apply_table_tweaks(self) -> None:
305
        """Apply table formatting improvements."""
306
        
307
    def apply_navigation_tweaks(self) -> None:
308
        """Apply navigation improvements."""
309
        
310
    def apply_responsive_tweaks(self) -> None:
311
        """Apply responsive design improvements."""
312
```
313

314
### Cross-Reference Improvements
315

316
Enhanced cross-referencing with better resolution and formatting.
317

318
```python { .api }
319
def improve_cross_references(app: Sphinx) -> None:
320
    """
321
    Apply cross-reference improvements.
322
    
323
    Args:
324
        app: Sphinx application instance
325
    """
326

327
def enhance_xref_resolution(app: Sphinx) -> None:
328
    """
329
    Enhance cross-reference resolution logic.
330
    
331
    Args:
332
        app: Sphinx application instance
333
    """
334

335
def fix_xref_formatting(app: Sphinx) -> None:
336
    """
337
    Fix cross-reference formatting issues.
338
    
339
    Args:
340
        app: Sphinx application instance
341
    """
342

343
class CrossRefTweaks:
344
    """Cross-reference enhancement utilities."""
345
    
346
    def __init__(self, app: Sphinx) -> None: ...
347
    
348
    def improve_resolution(self) -> None:
349
        """Improve cross-reference resolution."""
350
        
351
    def enhance_formatting(self) -> None:
352
        """Enhance cross-reference formatting."""
353
```
354

355
### Search Improvements
356

357
Enhancements to Sphinx's built-in search functionality.
358

359
```python { .api }
360
def enhance_search_index(app: Sphinx) -> None:
361
    """
362
    Enhance search index generation.
363
    
364
    Args:
365
        app: Sphinx application instance
366
    """
367

368
def improve_search_results(app: Sphinx) -> None:
369
    """
370
    Improve search result ranking and display.
371
    
372
    Args:
373
        app: Sphinx application instance
374
    """
375

376
class SearchTweaks:
377
    """Search functionality improvements."""
378
    
379
    def __init__(self, app: Sphinx) -> None: ...
380
    
381
    def enhance_indexing(self) -> None:
382
        """Enhance search indexing."""
383
        
384
    def improve_ranking(self) -> None:
385
        """Improve search result ranking."""
386
```
387

388
### Theme Compatibility
389

390
Compatibility improvements for various Sphinx themes.
391

392
```python { .api }
393
def ensure_theme_compatibility(app: Sphinx, theme_name: str) -> None:
394
    """
395
    Ensure compatibility with specified theme.
396
    
397
    Args:
398
        app: Sphinx application instance
399
        theme_name: Name of the theme
400
    """
401

402
def fix_theme_css_conflicts(app: Sphinx) -> None:
403
    """
404
    Fix CSS conflicts with themes.
405
    
406
    Args:
407
        app: Sphinx application instance
408
    """
409

410
class ThemeCompatibility:
411
    """Theme compatibility utilities."""
412
    
413
    SUPPORTED_THEMES = ['alabaster', 'sphinx_rtd_theme', 'furo', 'book_theme']
414
    
415
    def __init__(self, app: Sphinx) -> None: ...
416
    
417
    def detect_theme(self) -> str:
418
        """Detect current theme."""
419
        
420
    def apply_theme_fixes(self, theme_name: str) -> None:
421
        """Apply fixes for specific theme."""
422
```
423

424
### Performance Optimizations
425

426
Small performance optimizations for faster documentation builds.
427

428
```python { .api }
429
def apply_performance_tweaks(app: Sphinx) -> None:
430
    """
431
    Apply performance optimization tweaks.
432
    
433
    Args:
434
        app: Sphinx application instance
435
    """
436

437
def optimize_node_processing(app: Sphinx) -> None:
438
    """
439
    Optimize document node processing.
440
    
441
    Args:
442
        app: Sphinx application instance
443
    """
444

445
def cache_expensive_operations(app: Sphinx) -> None:
446
    """
447
    Add caching for expensive operations.
448
    
449
    Args:
450
        app: Sphinx application instance
451
    """
452

453
class PerformanceTweaks:
454
    """Performance optimization utilities."""
455
    
456
    def __init__(self, app: Sphinx) -> None: ...
457
    
458
    def optimize_parsing(self) -> None:
459
        """Optimize document parsing."""
460
        
461
    def optimize_rendering(self) -> None:
462
        """Optimize output rendering."""
463
        
464
    def add_caching(self) -> None:
465
        """Add performance caching."""
466
```
467

468
### Configuration Tweaks
469

470
Improvements to configuration handling and validation.
471

472
```python { .api }
473
def enhance_config_validation(app: Sphinx) -> None:
474
    """
475
    Enhance configuration validation with better error messages.
476
    
477
    Args:
478
        app: Sphinx application instance
479
    """
480

481
def add_config_helpers(app: Sphinx) -> None:
482
    """
483
    Add configuration helper utilities.
484
    
485
    Args:
486
        app: Sphinx application instance
487
    """
488

489
class ConfigTweaks:
490
    """Configuration enhancement utilities."""
491
    
492
    def __init__(self, app: Sphinx) -> None: ...
493
    
494
    def improve_validation(self) -> None:
495
        """Improve configuration validation."""
496
        
497
    def add_shortcuts(self) -> None:
498
        """Add configuration shortcuts."""
499
        
500
    def enhance_error_messages(self) -> None:
501
        """Enhance configuration error messages."""
502
```
503

504
### Extension Integration
505

506
Improvements to extension loading and integration.
507

508
```python { .api }
509
def improve_extension_loading(app: Sphinx) -> None:
510
    """
511
    Improve extension loading with better error handling.
512
    
513
    Args:
514
        app: Sphinx application instance
515
    """
516

517
def enhance_extension_metadata(app: Sphinx) -> None:
518
    """
519
    Enhance extension metadata handling.
520
    
521
    Args:
522
        app: Sphinx application instance
523
    """
524

525
def fix_extension_conflicts(app: Sphinx) -> None:
526
    """
527
    Fix common extension conflicts.
528
    
529
    Args:
530
        app: Sphinx application instance
531
    """
532
```
533

534
### Usage Examples
535

536
Configuration in `conf.py`:
537

538
```python
539
# Enable all tweaks and enhancements
540
extensions = [
541
    'sphinx_toolbox.tweaks',
542
    # Individual tweak extensions
543
    'sphinx_toolbox.tweaks.tabsize',
544
    'sphinx_toolbox.tweaks.param_dash', 
545
    'sphinx_toolbox.tweaks.footnote_symbols',
546
    'sphinx_toolbox.tweaks.latex_layout',
547
    'sphinx_toolbox.tweaks.latex_toc',
548
]
549

550
# Configure tweak behavior
551
tabsize = 4
552
footnote_symbols = 'symbols'  # 'symbols', 'numbers', 'roman'
553
latex_tweaks_enable = True
554
```
555

556
Using in documents:
557

558
```rst
559
This text has a footnote [#footnote1]_ that will use symbols.
560

561
.. [#footnote1] Footnote text with enhanced formatting.
562

563
.. code-block:: python
564
   :tab-width: 4
565
   
566
   # This code block will have consistent tab handling
567
   def example():
568
       return "Enhanced formatting"
569
```