0
# Theme Configuration
1

2
Core theme setup, registration, and configuration management for the Sphinx Awesome Theme. This module handles theme initialization, option validation, deprecated setting migration, and integration with Sphinx's plugin system.
3

4
## Capabilities
5

6
### Main Setup Function
7

8
Registers the theme with Sphinx and configures all theme extensions, event handlers, and custom functionality.
9

10
```python { .api }
11
def setup(app: Sphinx) -> dict[str, Any]:
12
    """
13
    Register the theme and its extensions with Sphinx.
14
    
15
    Parameters:
16
    - app (Sphinx): The Sphinx application instance
17
    
18
    Returns:
19
    dict[str, Any]: Theme metadata with version and parallel processing flags
20
    """
21
```
22

23
This function performs comprehensive theme initialization:
24
- Registers the HTML theme with Sphinx
25
- Adds custom directives (AwesomeCodeBlock)
26
- Configures Pygments integration with dark mode support
27
- Adds JavaScript and CSS files
28
- Connects event handlers for logo management, HTML post-processing, and TOC manipulation
29
- Sets up JSON builder customizations
30

31
### Theme Options Configuration
32

33
Comprehensive configuration class that defines all available theme customization options.
34

35
```python { .api }
36
@dataclass
37
class ThemeOptions:
38
    """
39
    Helper class for configuring the Awesome Theme.
40
    Each attribute becomes a key in the html_theme_options dictionary.
41
    """
42
    
43
    show_prev_next: bool = True
44
    """If True, includes links to previous and next pages in hierarchy."""
45
    
46
    show_breadcrumbs: bool = True
47
    """If True, includes breadcrumb navigation links on every page except root."""
48
    
49
    breadcrumbs_separator: str = "/"
50
    """The separator character for breadcrumb links."""
51
    
52
    awesome_headerlinks: bool = True
53
    """If True, clicking a headerlink copies its URL to the clipboard."""
54
    
55
    show_scrolltop: bool = False
56
    """If True, shows a button that scrolls to the top when clicked."""
57
    
58
    awesome_external_links: bool = False
59
    """If True, adds icons and rel="nofollow noopener" to external links."""
60
    
61
    main_nav_links: dict[str, str] = field(default_factory=dict)
62
    """Dictionary with links to include in the site header."""
63
    
64
    extra_header_link_icons: dict[str, LinkIcon] = field(default_factory=dict)
65
    """Dictionary with extra icons to include on the right of the search bar."""
66
    
67
    logo_light: str | None = None
68
    """Path to a logo for light mode. Must provide both logos if using separate modes."""
69
    
70
    logo_dark: str | None = None
71
    """Path to a logo for dark mode. Must provide both logos if using separate modes."""
72
    
73
    globaltoc_includehidden: bool = True
74
    """If True, includes entries from hidden toctree directives in the sidebar."""
75
```
76

77
### Deprecated Options Handling
78

79
Automatic migration of deprecated configuration options with warning messages.
80

81
```python { .api }
82
def deprecated_options(app: Sphinx) -> None:
83
    """
84
    Checks for deprecated html_theme_options and issues warnings.
85
    Automatically migrates deprecated options to current equivalents.
86
    
87
    Parameters:
88
    - app (Sphinx): The Sphinx application instance
89
    """
90
```
91

92
Handles migration for:
93
- `nav_include_hidden` → `globaltoc_includehidden`
94
- `show_nav` → `html_sidebars` configuration
95
- `extra_header_links` → `main_nav_links` and `extra_header_link_icons`
96

97
### Version Management
98

99
Package version detection and management.
100

101
```python { .api }
102
__version__: str
103
"""Package version obtained from pyproject.toml via importlib.metadata.version()"""
104
```
105

106
## Configuration Examples
107

108
### Basic Theme Setup
109

110
```python
111
# In conf.py
112
html_theme = "sphinxawesome_theme"
113

114
html_theme_options = {
115
    "show_prev_next": True,
116
    "show_breadcrumbs": True,
117
    "awesome_headerlinks": True,
118
}
119
```
120

121
### Advanced Navigation Configuration
122

123
```python
124
html_theme_options = {
125
    "main_nav_links": {
126
        "Home": "/",
127
        "Documentation": "/docs/",
128
        "API Reference": "/api/",
129
        "Examples": "/examples/"
130
    },
131
    "extra_header_link_icons": {
132
        "GitHub": {
133
            "link": "https://github.com/user/repo",
134
            "icon": "<svg>...</svg>"
135
        }
136
    }
137
}
138
```
139

140
### Logo Configuration
141

142
```python
143
html_theme_options = {
144
    "logo_light": "assets/logo-light.svg",
145
    "logo_dark": "assets/logo-dark.svg"
146
}
147
```
148

149
## Error Handling
150

151
The theme includes comprehensive validation:
152
- Warns when both `html_logo` and theme logo options are used
153
- Requires both light and dark logos when using separate mode logos
154
- Validates deprecated options and provides migration paths
155
- Handles missing logo files gracefully with warning messages