tessl/pypi-sphinxawesome-theme
An awesome theme for the Sphinx documentation generator with enhanced features, custom code highlighting, and modern responsive design
theme-configuration.mddocs/
Theme Configuration
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.
Capabilities
Main Setup Function
Registers the theme with Sphinx and configures all theme extensions, event handlers, and custom functionality.
def setup(app: Sphinx) -> dict[str, Any]:
"""
Register the theme and its extensions with Sphinx.
Parameters:
- app (Sphinx): The Sphinx application instance
Returns:
dict[str, Any]: Theme metadata with version and parallel processing flags
"""This function performs comprehensive theme initialization:
- Registers the HTML theme with Sphinx
- Adds custom directives (AwesomeCodeBlock)
- Configures Pygments integration with dark mode support
- Adds JavaScript and CSS files
- Connects event handlers for logo management, HTML post-processing, and TOC manipulation
- Sets up JSON builder customizations
Theme Options Configuration
Comprehensive configuration class that defines all available theme customization options.
@dataclass
class ThemeOptions:
"""
Helper class for configuring the Awesome Theme.
Each attribute becomes a key in the html_theme_options dictionary.
"""
show_prev_next: bool = True
"""If True, includes links to previous and next pages in hierarchy."""
show_breadcrumbs: bool = True
"""If True, includes breadcrumb navigation links on every page except root."""
breadcrumbs_separator: str = "/"
"""The separator character for breadcrumb links."""
awesome_headerlinks: bool = True
"""If True, clicking a headerlink copies its URL to the clipboard."""
show_scrolltop: bool = False
"""If True, shows a button that scrolls to the top when clicked."""
awesome_external_links: bool = False
"""If True, adds icons and rel="nofollow noopener" to external links."""
main_nav_links: dict[str, str] = field(default_factory=dict)
"""Dictionary with links to include in the site header."""
extra_header_link_icons: dict[str, LinkIcon] = field(default_factory=dict)
"""Dictionary with extra icons to include on the right of the search bar."""
logo_light: str | None = None
"""Path to a logo for light mode. Must provide both logos if using separate modes."""
logo_dark: str | None = None
"""Path to a logo for dark mode. Must provide both logos if using separate modes."""
globaltoc_includehidden: bool = True
"""If True, includes entries from hidden toctree directives in the sidebar."""Deprecated Options Handling
Automatic migration of deprecated configuration options with warning messages.
def deprecated_options(app: Sphinx) -> None:
"""
Checks for deprecated html_theme_options and issues warnings.
Automatically migrates deprecated options to current equivalents.
Parameters:
- app (Sphinx): The Sphinx application instance
"""Handles migration for:
nav_include_hidden→globaltoc_includehiddenshow_nav→html_sidebarsconfigurationextra_header_links→main_nav_linksandextra_header_link_icons
Version Management
Package version detection and management.
__version__: str
"""Package version obtained from pyproject.toml via importlib.metadata.version()"""Configuration Examples
Basic Theme Setup
# In conf.py
html_theme = "sphinxawesome_theme"
html_theme_options = {
"show_prev_next": True,
"show_breadcrumbs": True,
"awesome_headerlinks": True,
}Advanced Navigation Configuration
html_theme_options = {
"main_nav_links": {
"Home": "/",
"Documentation": "/docs/",
"API Reference": "/api/",
"Examples": "/examples/"
},
"extra_header_link_icons": {
"GitHub": {
"link": "https://github.com/user/repo",
"icon": "<svg>...</svg>"
}
}
}Logo Configuration
html_theme_options = {
"logo_light": "assets/logo-light.svg",
"logo_dark": "assets/logo-dark.svg"
}Error Handling
The theme includes comprehensive validation:
- Warns when both
html_logoand theme logo options are used - Requires both light and dark logos when using separate mode logos
- Validates deprecated options and provides migration paths
- Handles missing logo files gracefully with warning messages
Install with Tessl CLI
npx tessl i tessl/pypi-sphinxawesome-theme