0
# Sphinx Awesome Theme
1

2
A comprehensive Sphinx theme that transforms standard documentation into beautiful, modern websites with enhanced features including custom code highlighting, interactive navigation, responsive design, and extensive customization options. The theme provides advanced code block features with syntax highlighting for added/removed lines and placeholder text, enhanced navigation with collapsible sections and breadcrumbs, and seamless integration with popular Sphinx extensions.
3

4
## Package Information
5

6
- **Package Name**: sphinxawesome-theme
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install sphinxawesome-theme`
10

11
## Core Imports
12

13
```python
14
import sphinxawesome_theme
15
```
16

17
For theme configuration in Sphinx `conf.py`:
18

19
```python
20
html_theme = "sphinxawesome_theme"
21
```
22

23
## Basic Usage
24

25
```python
26
# In your Sphinx conf.py file
27
html_theme = "sphinxawesome_theme"
28

29
# Configure theme options
30
html_theme_options = {
31
    "show_prev_next": True,
32
    "show_breadcrumbs": True,
33
    "awesome_headerlinks": True,
34
    "show_scrolltop": False,
35
    "awesome_external_links": False,
36
    "main_nav_links": {
37
        "Home": "/",
38
        "Docs": "/docs/",
39
        "API": "/api/"
40
    },
41
    "logo_light": "assets/logo-light.svg",
42
    "logo_dark": "assets/logo-dark.svg"
43
}
44

45
# Enable enhanced code highlighting
46
extensions = [
47
    # ... other extensions
48
]
49

50
# Configure dark mode syntax highlighting
51
pygments_style = "default"
52
pygments_style_dark = "monokai"
53
```
54

55
## Architecture
56

57
The Sphinx Awesome Theme follows a modular architecture with several key components:
58

59
- **Theme Registration**: Main entry point that registers the theme with Sphinx through the plugin system
60
- **Enhanced Code Blocks**: Custom directive extending Sphinx's code-block with additional highlighting options
61
- **Custom Pygments Integration**: Specialized formatters and lexers for advanced syntax highlighting
62
- **HTML Post-Processing**: BeautifulSoup-based pipeline for modifying generated HTML
63
- **Template Integration**: Jinja2 functions and custom template modifications
64
- **Asset Management**: Logo handling and static file processing
65

66
This architecture enables comprehensive customization while maintaining compatibility with standard Sphinx workflows and extensions.
67

68
## Capabilities
69

70
### Theme Configuration
71

72
Core theme setup, registration, and configuration management including theme options validation, deprecated option handling, and Sphinx integration.
73

74
```python { .api }
75
def setup(app: Sphinx) -> dict[str, Any]: ...
76

77
class ThemeOptions:
78
    show_prev_next: bool = True
79
    show_breadcrumbs: bool = True
80
    breadcrumbs_separator: str = "/"
81
    awesome_headerlinks: bool = True
82
    show_scrolltop: bool = False
83
    awesome_external_links: bool = False
84
    main_nav_links: dict[str, str] = field(default_factory=dict)
85
    extra_header_link_icons: dict[str, LinkIcon] = field(default_factory=dict)
86
    logo_light: str | None = None
87
    logo_dark: str | None = None
88
    globaltoc_includehidden: bool = True
89
```
90

91
[Theme Configuration](./theme-configuration.md)
92

93
### Enhanced Code Highlighting
94

95
Advanced code block functionality with support for highlighting added/removed lines, placeholder text emphasis, and custom Pygments formatters with dark mode support.
96

97
```python { .api }
98
class AwesomeCodeBlock(CodeBlock):
99
    new_options = {
100
        "emphasize-added": directives.unchanged_required,
101
        "emphasize-removed": directives.unchanged_required,
102
        "emphasize-text": directives.unchanged_required,
103
    }
104

105
class AwesomePygmentsBridge(PygmentsBridge):
106
    html_formatter = AwesomeHtmlFormatter
107

108
class AwesomeHtmlFormatter(HtmlFormatter):
109
    def __init__(self, **options: Any) -> None: ...
110
```
111

112
[Enhanced Code Highlighting](./code-highlighting.md)
113

114
### HTML Post-Processing
115

116
Comprehensive HTML modification pipeline using BeautifulSoup for adding interactive features, improving navigation, and enhancing accessibility.
117

118
```python { .api }
119
def post_process_html(app: Sphinx, exc: Exception | None) -> None: ...
120
def modify_html(html_filename: str, app: Sphinx) -> None: ...
121
def collapsible_nav(tree: BeautifulSoup) -> None: ...
122
def headerlinks(tree: BeautifulSoup) -> None: ...
123
def external_links(tree: BeautifulSoup) -> None: ...
124
def scrollspy(tree: BeautifulSoup) -> None: ...
125
```
126

127
[HTML Post-Processing](./html-postprocessing.md)
128

129
### Logo and Asset Management
130

131
Flexible logo system supporting separate light and dark mode logos with automatic asset copying and template context management.
132

133
```python { .api }
134
def get_theme_options(app: Sphinx) -> Any: ...
135
def update_config(app: Sphinx) -> None: ...
136
def setup_logo_path(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...
137
def copy_logos(app: Sphinx, exc: Exception | None) -> None: ...
138
```
139

140
[Logo and Asset Management](./logo-management.md)
141

142
### Template Functions
143

144
Custom Jinja2 functions and template modifications including canonical URL fixes and template context enhancements.
145

146
```python { .api }
147
def setup_jinja(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...
148
```
149

150
[Template Functions](./template-functions.md)
151

152
### Table of Contents Manipulation
153

154
Advanced TOC processing that removes page titles from navigation and restructures hierarchical content for improved usability.
155

156
```python { .api }
157
def change_toc(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...
158
def findall(node: Node, selection: Node) -> Any: ...
159
```
160

161
[Table of Contents](./toc-manipulation.md)
162

163
### JSON Serialization
164

165
Custom JSON serialization system for template context data that handles non-serializable Jinja2 functions and theme-specific data.
166

167
```python { .api }
168
class AwesomeJSONEncoder(json.JSONEncoder):
169
    def default(self, obj: Any) -> str: ...
170

171
def dump(obj: Any, fp: IO[str], *args: Any, **kwargs: Any) -> None: ...
172
def dumps(obj: Any, *args: Any, **kwargs: Any) -> str: ...
173
def load(*args: Any, **kwargs: Any) -> Any: ...
174
def loads(*args: Any, **kwargs: Any) -> Any: ...
175
```
176

177
[JSON Serialization](./json-serialization.md)
178

179
### Theme Builder
180

181
Custom HTML builder that extends Sphinx's StandaloneHTMLBuilder with enhanced Pygments highlighting and dark mode CSS support.
182

183
```python { .api }
184
class AwesomeHTMLBuilder(StandaloneHTMLBuilder):
185
    def init_highlighter(self) -> None: ...
186
    def create_pygments_style_file(self) -> None: ...
187
```
188

189
[Theme Builder](./theme-builder.md)
190

191
### Deprecated Options
192

193
Backward compatibility system that detects and migrates deprecated configuration options with appropriate warnings and automatic conversion.
194

195
```python { .api }
196
def check_deprecated(app: Sphinx, config: Config) -> None: ...
197
def setup(app: Sphinx) -> dict[str, Any]: ...
198
```
199

200
[Deprecated Options](./deprecated-options.md)
201

202
## Types
203

204
```python { .api }
205
class LinkIcon(TypedDict):
206
    """A link to an external resource, represented by an icon."""
207
    link: str  # The absolute URL to an external resource
208
    icon: str  # An SVG icon as a string
209
```