or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

code-highlighting.mddeprecated-options.mdhtml-postprocessing.mdindex.mdjson-serialization.mdlogo-management.mdtemplate-functions.mdtheme-builder.mdtheme-configuration.mdtoc-manipulation.md
tile.json

tessl/pypi-sphinxawesome-theme

An awesome theme for the Sphinx documentation generator with enhanced features, custom code highlighting, and modern responsive design

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinxawesome-theme@5.3.x

To install, run

npx @tessl/cli install tessl/pypi-sphinxawesome-theme@5.3.0

index.mddocs/

Sphinx Awesome Theme

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.

Package Information

  • Package Name: sphinxawesome-theme
  • Package Type: pypi
  • Language: Python
  • Installation: pip install sphinxawesome-theme

Core Imports

import sphinxawesome_theme

For theme configuration in Sphinx conf.py:

html_theme = "sphinxawesome_theme"

Basic Usage

# In your Sphinx conf.py file
html_theme = "sphinxawesome_theme"

# Configure theme options
html_theme_options = {
    "show_prev_next": True,
    "show_breadcrumbs": True,
    "awesome_headerlinks": True,
    "show_scrolltop": False,
    "awesome_external_links": False,
    "main_nav_links": {
        "Home": "/",
        "Docs": "/docs/",
        "API": "/api/"
    },
    "logo_light": "assets/logo-light.svg",
    "logo_dark": "assets/logo-dark.svg"
}

# Enable enhanced code highlighting
extensions = [
    # ... other extensions
]

# Configure dark mode syntax highlighting
pygments_style = "default"
pygments_style_dark = "monokai"

Architecture

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

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

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

Capabilities

Theme Configuration

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

def setup(app: Sphinx) -> dict[str, Any]: ...

class ThemeOptions:
    show_prev_next: bool = True
    show_breadcrumbs: bool = True
    breadcrumbs_separator: str = "/"
    awesome_headerlinks: bool = True
    show_scrolltop: bool = False
    awesome_external_links: bool = False
    main_nav_links: dict[str, str] = field(default_factory=dict)
    extra_header_link_icons: dict[str, LinkIcon] = field(default_factory=dict)
    logo_light: str | None = None
    logo_dark: str | None = None
    globaltoc_includehidden: bool = True

Theme Configuration

Enhanced Code Highlighting

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

class AwesomeCodeBlock(CodeBlock):
    new_options = {
        "emphasize-added": directives.unchanged_required,
        "emphasize-removed": directives.unchanged_required,
        "emphasize-text": directives.unchanged_required,
    }

class AwesomePygmentsBridge(PygmentsBridge):
    html_formatter = AwesomeHtmlFormatter

class AwesomeHtmlFormatter(HtmlFormatter):
    def __init__(self, **options: Any) -> None: ...

Enhanced Code Highlighting

HTML Post-Processing

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

def post_process_html(app: Sphinx, exc: Exception | None) -> None: ...
def modify_html(html_filename: str, app: Sphinx) -> None: ...
def collapsible_nav(tree: BeautifulSoup) -> None: ...
def headerlinks(tree: BeautifulSoup) -> None: ...
def external_links(tree: BeautifulSoup) -> None: ...
def scrollspy(tree: BeautifulSoup) -> None: ...

HTML Post-Processing

Logo and Asset Management

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

def get_theme_options(app: Sphinx) -> Any: ...
def update_config(app: Sphinx) -> None: ...
def setup_logo_path(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...
def copy_logos(app: Sphinx, exc: Exception | None) -> None: ...

Logo and Asset Management

Template Functions

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

def setup_jinja(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...

Template Functions

Table of Contents Manipulation

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

def change_toc(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree: Node) -> None: ...
def findall(node: Node, selection: Node) -> Any: ...

Table of Contents

JSON Serialization

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

class AwesomeJSONEncoder(json.JSONEncoder):
    def default(self, obj: Any) -> str: ...

def dump(obj: Any, fp: IO[str], *args: Any, **kwargs: Any) -> None: ...
def dumps(obj: Any, *args: Any, **kwargs: Any) -> str: ...
def load(*args: Any, **kwargs: Any) -> Any: ...
def loads(*args: Any, **kwargs: Any) -> Any: ...

JSON Serialization

Theme Builder

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

class AwesomeHTMLBuilder(StandaloneHTMLBuilder):
    def init_highlighter(self) -> None: ...
    def create_pygments_style_file(self) -> None: ...

Theme Builder

Deprecated Options

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

def check_deprecated(app: Sphinx, config: Config) -> None: ...
def setup(app: Sphinx) -> dict[str, Any]: ...

Deprecated Options

Types

class LinkIcon(TypedDict):
    """A link to an external resource, represented by an icon."""
    link: str  # The absolute URL to an external resource
    icon: str  # An SVG icon as a string