0
# Enhanced Code Highlighting
1
2
Advanced code block functionality that extends Sphinx's standard code highlighting with support for emphasizing added/removed lines, placeholder text highlighting, and custom Pygments formatters with comprehensive dark mode support.
3
4
## Capabilities
5
6
### Enhanced Code Block Directive
7
8
Custom directive that extends Sphinx's built-in code-block directive with additional highlighting options.
9
10
```python { .api }
11
class AwesomeCodeBlock(CodeBlock):
12
"""
13
Extension of the Sphinx code-block directive with additional highlighting options.
14
15
New options:
16
- :emphasize-added: highlight added lines
17
- :emphasize-removed: highlight removed lines
18
- :emphasize-text: highlight placeholder text
19
"""
20
21
new_options = {
22
"emphasize-added": directives.unchanged_required,
23
"emphasize-removed": directives.unchanged_required,
24
"emphasize-text": directives.unchanged_required,
25
}
26
27
def _get_line_numbers(self, option: Literal["emphasize-added", "emphasize-removed"]) -> list[int] | None:
28
"""Parse the line numbers for the emphasize-added and emphasize-removed options."""
29
30
def _extra_args(self, node: Node, hl_added: list[int] | None, hl_removed: list[int] | None) -> None:
31
"""Set extra attributes for line highlighting."""
32
33
def run(self) -> list[Node]:
34
"""Handle parsing extra options for highlighting."""
35
```
36
37
### Custom Pygments Bridge
38
39
Enhanced Pygments integration that handles placeholder text highlighting and provides dark mode stylesheet support.
40
41
```python { .api }
42
class AwesomePygmentsBridge(PygmentsBridge):
43
"""Extends PygmentsBridge to handle highlighting placeholder text."""
44
45
html_formatter = AwesomeHtmlFormatter
46
47
def get_lexer(self, source: str, lang: str, opts: dict[str, Any] | None = None,
48
force: bool = False, location: Any = None) -> Lexer:
49
"""
50
Extends PygmentsBridge.get_lexer method.
51
Adds a filter to lexers if the hl_text option is present.
52
"""
53
54
def highlight_block(self, source: str, lang: str, opts: dict[str, Any] | None = None,
55
force: bool = False, location: Any = None, **kwargs: Any) -> str:
56
"""
57
Extends PygmentsBridge.highlight_block method.
58
Called when Sphinx transforms document tree to HTML and encounters code blocks.
59
"""
60
61
def get_stylesheet(self, arg: str | None = None) -> str:
62
"""
63
Override PygmentsBridge.get_stylesheet method.
64
Allows prepending all Pygments classes with a common prefix, such as .dark.
65
"""
66
```
67
68
### Custom HTML Formatter
69
70
Specialized Pygments HTML formatter that handles highlighting of added, removed, and emphasized lines.
71
72
```python { .api }
73
class AwesomeHtmlFormatter(HtmlFormatter):
74
"""Custom Pygments HTML formatter for highlighting added or removed lines."""
75
76
def _get_line_numbers(self, options: dict[str, Any], which: Literal["hl_added", "hl_removed"]) -> set[int]:
77
"""Get the lines to be added or removed."""
78
79
def _highlight_lines(self, tokensource: TokenStream) -> TokenStream:
80
"""
81
Highlight added, removed, and emphasized lines.
82
In contrast to Pygments, use <mark>, <ins>, and <del> elements.
83
"""
84
85
def __init__(self, **options: Any) -> None:
86
"""
87
Implement hl_added and hl_removed options.
88
Also sets linespans and wrapcode options to True.
89
90
Parameters:
91
- **options: Formatter options including hl_added, hl_removed lists
92
"""
93
94
def format_unencoded(self, tokensource: TokenStream, outfile: Any) -> None:
95
"""
96
Overwrite method to handle emphasized, added, and removed lines.
97
Uses <mark>, <ins>, and <del> elements for line highlighting.
98
"""
99
```
100
101
### Placeholder Text Filter
102
103
Pygments filter for marking up placeholder text within code blocks.
104
105
```python { .api }
106
def _replace_placeholders(ttype: TokenType, value: str, regex: Pattern[str]) -> TokenStream:
107
"""Replace every occurrence of regex with Generic.Emph token."""
108
109
class AwesomePlaceholders(Filter):
110
"""
111
A Pygments filter for marking up placeholder text.
112
Highlights specified text patterns with Generic.Emph token.
113
"""
114
115
def __init__(self, **options: str) -> None:
116
"""
117
Create an instance of the AwesomePlaceholders filter.
118
119
Parameters:
120
- **options: Filter options including hl_text list
121
"""
122
123
def filter(self, _lexer: Any, stream: TokenStream) -> TokenStream:
124
"""Filter on all tokens to replace placeholders with emphasized tokens."""
125
```
126
127
### Enhanced HTML Builder
128
129
HTML builder that overrides Pygments CSS handling methods for dark mode support.
130
131
```python { .api }
132
class AwesomeHTMLBuilder(StandaloneHTMLBuilder):
133
"""HTML builder that overrides methods related to handling CSS for Pygments."""
134
135
def init_highlighter(self) -> None:
136
"""Initialize Pygments highlighters with dark mode support."""
137
138
def create_pygments_style_file(self) -> None:
139
"""Create CSS file for Pygments with combined light and dark mode styles."""
140
```
141
142
## Usage Examples
143
144
### Basic Enhanced Code Block
145
146
```rst
147
.. code-block:: python
148
:emphasize-added: 2,4
149
:emphasize-removed: 6
150
:emphasize-text: placeholder_value
151
152
def process_data(data):
153
# This line will be highlighted as added
154
result = transform(data)
155
# This line will also be highlighted as added
156
enhanced_result = enhance(result)
157
# This line will be highlighted as removed
158
return placeholder_value
159
```
160
161
### Dark Mode Configuration
162
163
```python
164
# In conf.py
165
pygments_style = "default" # Light mode style
166
pygments_style_dark = "monokai" # Dark mode style
167
168
html_theme_options = {
169
"awesome_headerlinks": True,
170
}
171
```
172
173
### Custom Placeholder Highlighting
174
175
```python
176
# The AwesomePlaceholders filter automatically highlights
177
# text specified in the :emphasize-text: option
178
lexer.add_filter(AwesomePlaceholders(hl_text=["PLACEHOLDER", "TODO"]))
179
```
180
181
## Configuration Options
182
183
### Pygments Style Configuration
184
185
```python
186
# Configure Pygments styles for light and dark modes
187
pygments_style = "default" # Style for light mode
188
pygments_style_dark = "monokai" # Style for dark mode (optional)
189
```
190
191
### Code Block Options
192
193
Available options for the enhanced code-block directive:
194
195
- `:emphasize-added: 1,3,5-7` - Highlight lines as added (uses `<ins>` elements)
196
- `:emphasize-removed: 2,4` - Highlight lines as removed (uses `<del>` elements)
197
- `:emphasize-text: placeholder` - Highlight specific text patterns (uses `Generic.Emph` token)
198
199
## HTML Output
200
201
The enhanced formatter produces structured HTML output:
202
203
```html
204
<pre><code>
205
<span id="line-1">def example():</span>
206
<ins><span id="line-2"> # Added line</span></ins>
207
<del><span id="line-3"> # Removed line</span></del>
208
<mark><span id="line-4"> # Emphasized line</span></mark>
209
</code></pre>
210
```
211
212
## Types
213
214
```python { .api }
215
from typing import Generator, Tuple, Union, Pattern
216
from pygments.token import _TokenType
217
218
# Type aliases used throughout the highlighting system
219
TokenType = Union[_TokenType, int] # For Python 3.8 compatibility
220
TokenStream = Generator[Tuple[TokenType, str], None, None]
221
```
222
223
## Error Handling
224
225
The code highlighting system includes robust error handling:
226
- Invalid line numbers are logged with warnings
227
- Out-of-range line specifications are filtered out
228
- Missing lexers fall back to text highlighting
229
- Malformed placeholder patterns are ignored gracefully