0
# Deprecated Options
1

2
Comprehensive backward compatibility system that automatically detects deprecated configuration options, provides migration guidance, and ensures smooth transitions between theme versions. This system maintains compatibility with legacy configurations while encouraging adoption of modern alternatives.
3

4
## Capabilities
5

6
### Deprecated Configuration Detection
7

8
Main function that scans Sphinx configuration for deprecated options and provides automatic migration.
9

10
```python { .api }
11
def check_deprecated(app: Sphinx, config: Config) -> None:
12
    """
13
    Check the Sphinx configuration for deprecated options and migrate them automatically if possible.
14
    
15
    Scans configuration for deprecated theme options and:
16
    - Issues appropriate warning messages
17
    - Automatically migrates settings to modern equivalents
18
    - Provides guidance for manual migration when needed
19
    - Tracks whether any deprecated options were found
20
    
21
    Parameters:
22
    - app (Sphinx): The Sphinx application instance
23
    - config (Config): The Sphinx configuration object
24
    """
25
```
26

27
### Extension Setup
28

29
Extension registration that adds deprecated configuration values to Sphinx.
30

31
```python { .api }
32
def setup(app: Sphinx) -> dict[str, Any]:
33
    """
34
    Register the deprecated options extension.
35
    
36
    Registers deprecated configuration values with Sphinx so they
37
    don't cause errors when present in conf.py files. Also connects
38
    the deprecation checker to the config-inited event.
39
    
40
    Parameters:
41
    - app (Sphinx): The Sphinx application instance
42
    
43
    Returns:
44
    dict[str, Any]: Extension metadata with version and parallel processing flags
45
    """
46
```
47

48
## Deprecated Options Handled
49

50
### Theme Option Migrations
51

52
#### html_awesome_headerlinks → theme options
53

54
```python
55
# Deprecated (< 5.0)
56
html_awesome_headerlinks = True
57

58
# Modern equivalent
59
html_theme_options = {
60
    "awesome_headerlinks": True
61
}
62
```
63

64
#### html_awesome_external_links → theme options
65

66
```python
67
# Deprecated (< 5.0)
68
html_awesome_external_links = True
69

70
# Modern equivalent
71
html_theme_options = {
72
    "awesome_external_links": True
73
}
74
```
75

76
### Extension Migrations
77

78
#### html_awesome_docsearch → sphinx-docsearch extension
79

80
```python
81
# Deprecated (< 5.0)
82
html_awesome_docsearch = True
83

84
# Modern equivalent
85
extensions = [
86
    # ... other extensions
87
    "sphinx_docsearch"
88
]
89
```
90

91
#### html_collapsible_definitions → sphinx-design
92

93
```python
94
# Deprecated (< 5.0) 
95
html_collapsible_definitions = True
96

97
# Modern equivalent
98
extensions = [
99
    # ... other extensions
100
    "sphinx_design"
101
]
102
```
103

104
### Removed Features
105

106
#### html_awesome_code_headers (Removed)
107

108
```python
109
# This option no longer has any effect
110
html_awesome_code_headers = True  # Generates info message only
111
```
112

113
### Extension Inclusion Warnings
114

115
#### Theme as Extension (Deprecated)
116

117
```python
118
# Deprecated - no longer needed
119
extensions = [
120
    "sphinxawesome_theme",  # Warning: remove this
121
    "sphinxawesome_theme.highlighting"  # Warning: remove this
122
]
123

124
# Modern approach - just set the theme
125
html_theme = "sphinxawesome_theme"
126
```
127

128
## Migration Process
129

130
### Automatic Migration
131

132
The system automatically migrates compatible options:
133

134
1. **Detection**: Scans `config._raw_config` for deprecated keys
135
2. **Warning**: Issues deprecation warnings with migration guidance
136
3. **Migration**: Automatically updates configuration where possible
137
4. **Cleanup**: Removes deprecated keys from configuration
138

139
### Migration Example
140

141
```python
142
# Original deprecated configuration
143
html_awesome_headerlinks = True
144
html_awesome_external_links = False
145
html_awesome_docsearch = True
146

147
# After automatic migration
148
html_theme_options = {
149
    "awesome_headerlinks": True,      # Migrated automatically
150
    "awesome_external_links": False   # Migrated automatically
151
}
152
# html_awesome_docsearch generates warning only (manual migration required)
153
```
154

155
## Warning Messages
156

157
The system provides specific warning messages for each deprecated option:
158

159
### Configuration Option Warnings
160

161
```
162
`html_awesome_headerlinks` is deprecated. 
163
Use `html_theme_options = {'awesome_headerlinks: True '} instead.
164
```
165

166
```
167
`html_awesome_external_links` is deprecated. 
168
Use `html_theme_options = {'awesome_external_links: True '} instead.
169
```
170

171
### Extension Warnings
172

173
```
174
`html_awesome_docsearch` is deprecated. 
175
Use the `sphinx-docsearch` extension instead.
176
```
177

178
```
179
`html_collapsible_definitions` is deprecated. 
180
Use the `sphinx-design` extension instead.
181
```
182

183
### Theme Extension Warnings
184

185
```
186
Including `sphinxawesome_theme` in your `extensions` is deprecated. 
187
Setting `html_theme = "sphinxawesome_theme"` is enough.
188
```
189

190
```
191
You don't need to include the `sphinxawesome_theme.highlighting` extension anymore.
192
```
193

194
## Configuration Value Registration
195

196
The extension registers deprecated configuration values to prevent Sphinx errors:
197

198
```python { .api }
199
# Registered deprecated configuration values
200
app.add_config_value("html_collapsible_definitions", default=False, rebuild="html", types=(bool))
201
app.add_config_value("html_awesome_external_links", default=False, rebuild="html", types=(bool))
202
app.add_config_value("html_awesome_docsearch", default=False, rebuild="html", types=(bool))
203
app.add_config_value("docsearch_config", default={}, rebuild="html", types=(dict))
204
app.add_config_value("html_awesome_headerlinks", default=True, rebuild="html", types=(str))
205
app.add_config_value("html_awesome_code_headers", default=True, rebuild="html", types=(str))
206
```
207

208
## Usage Instructions
209

210
### Loading the Extension
211

212
```python
213
# In conf.py - add to extensions for deprecation checking
214
extensions = [
215
    "sphinxawesome_theme.deprecated",
216
    # ... other extensions
217
]
218
```
219

220
### Successful Migration Message
221

222
When no deprecated options are found:
223

224
```
225
No deprecated options found. You can remove the `sphinxawesome_theme.deprecated` extension.
226
```
227

228
## Implementation Details
229

230
### Event Integration
231

232
The deprecation checker connects to Sphinx's configuration system:
233

234
```python
235
app.connect("config-inited", check_deprecated)
236
```
237

238
This ensures checking happens after configuration is loaded but before the build process begins.
239

240
### Configuration Access
241

242
The system safely accesses raw configuration data:
243

244
```python
245
raw = config._raw_config
246
found_deprecated = False
247

248
if "deprecated_option" in raw:
249
    # Handle deprecated option
250
    found_deprecated = True
251
```
252

253
### Safe Migration
254

255
Migration preserves existing theme options:
256

257
```python
258
# Safely update theme options without overwriting existing values
259
config.html_theme_options["new_option"] = raw["deprecated_option"]
260
del raw["deprecated_option"]
261
```
262

263
## Maintenance and Evolution
264

265
### Adding New Deprecated Options
266

267
To deprecate a new option:
268

269
1. Add detection logic in `check_deprecated()`
270
2. Register the option in `setup()` if needed
271
3. Provide appropriate warning message
272
4. Implement automatic migration if possible
273

274
### Version Management
275

276
The extension tracks theme version for context:
277

278
```python
279
from . import __version__
280

281
return {
282
    "version": __version__,
283
    "parallel_read_safe": True,
284
    "parallel_write_safe": True,
285
}
286
```
287

288
This ensures deprecation messages are contextually appropriate for the theme version.