CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-sphinxawesome-theme

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

Overview
Eval results
Files

deprecated-options.mddocs/

Deprecated Options

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.

Capabilities

Deprecated Configuration Detection

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

def check_deprecated(app: Sphinx, config: Config) -> None:
    """
    Check the Sphinx configuration for deprecated options and migrate them automatically if possible.
    
    Scans configuration for deprecated theme options and:
    - Issues appropriate warning messages
    - Automatically migrates settings to modern equivalents
    - Provides guidance for manual migration when needed
    - Tracks whether any deprecated options were found
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    - config (Config): The Sphinx configuration object
    """

Extension Setup

Extension registration that adds deprecated configuration values to Sphinx.

def setup(app: Sphinx) -> dict[str, Any]:
    """
    Register the deprecated options extension.
    
    Registers deprecated configuration values with Sphinx so they
    don't cause errors when present in conf.py files. Also connects
    the deprecation checker to the config-inited event.
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    
    Returns:
    dict[str, Any]: Extension metadata with version and parallel processing flags
    """

Deprecated Options Handled

Theme Option Migrations

html_awesome_headerlinks → theme options

# Deprecated (< 5.0)
html_awesome_headerlinks = True

# Modern equivalent
html_theme_options = {
    "awesome_headerlinks": True
}

html_awesome_external_links → theme options

# Deprecated (< 5.0)
html_awesome_external_links = True

# Modern equivalent
html_theme_options = {
    "awesome_external_links": True
}

Extension Migrations

html_awesome_docsearch → sphinx-docsearch extension

# Deprecated (< 5.0)
html_awesome_docsearch = True

# Modern equivalent
extensions = [
    # ... other extensions
    "sphinx_docsearch"
]

html_collapsible_definitions → sphinx-design

# Deprecated (< 5.0) 
html_collapsible_definitions = True

# Modern equivalent
extensions = [
    # ... other extensions
    "sphinx_design"
]

Removed Features

html_awesome_code_headers (Removed)

# This option no longer has any effect
html_awesome_code_headers = True  # Generates info message only

Extension Inclusion Warnings

Theme as Extension (Deprecated)

# Deprecated - no longer needed
extensions = [
    "sphinxawesome_theme",  # Warning: remove this
    "sphinxawesome_theme.highlighting"  # Warning: remove this
]

# Modern approach - just set the theme
html_theme = "sphinxawesome_theme"

Migration Process

Automatic Migration

The system automatically migrates compatible options:

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

Migration Example

# Original deprecated configuration
html_awesome_headerlinks = True
html_awesome_external_links = False
html_awesome_docsearch = True

# After automatic migration
html_theme_options = {
    "awesome_headerlinks": True,      # Migrated automatically
    "awesome_external_links": False   # Migrated automatically
}
# html_awesome_docsearch generates warning only (manual migration required)

Warning Messages

The system provides specific warning messages for each deprecated option:

Configuration Option Warnings

`html_awesome_headerlinks` is deprecated. 
Use `html_theme_options = {'awesome_headerlinks: True '} instead.
`html_awesome_external_links` is deprecated. 
Use `html_theme_options = {'awesome_external_links: True '} instead.

Extension Warnings

`html_awesome_docsearch` is deprecated. 
Use the `sphinx-docsearch` extension instead.
`html_collapsible_definitions` is deprecated. 
Use the `sphinx-design` extension instead.

Theme Extension Warnings

Including `sphinxawesome_theme` in your `extensions` is deprecated. 
Setting `html_theme = "sphinxawesome_theme"` is enough.
You don't need to include the `sphinxawesome_theme.highlighting` extension anymore.

Configuration Value Registration

The extension registers deprecated configuration values to prevent Sphinx errors:

# Registered deprecated configuration values
app.add_config_value("html_collapsible_definitions", default=False, rebuild="html", types=(bool))
app.add_config_value("html_awesome_external_links", default=False, rebuild="html", types=(bool))
app.add_config_value("html_awesome_docsearch", default=False, rebuild="html", types=(bool))
app.add_config_value("docsearch_config", default={}, rebuild="html", types=(dict))
app.add_config_value("html_awesome_headerlinks", default=True, rebuild="html", types=(str))
app.add_config_value("html_awesome_code_headers", default=True, rebuild="html", types=(str))

Usage Instructions

Loading the Extension

# In conf.py - add to extensions for deprecation checking
extensions = [
    "sphinxawesome_theme.deprecated",
    # ... other extensions
]

Successful Migration Message

When no deprecated options are found:

No deprecated options found. You can remove the `sphinxawesome_theme.deprecated` extension.

Implementation Details

Event Integration

The deprecation checker connects to Sphinx's configuration system:

app.connect("config-inited", check_deprecated)

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

Configuration Access

The system safely accesses raw configuration data:

raw = config._raw_config
found_deprecated = False

if "deprecated_option" in raw:
    # Handle deprecated option
    found_deprecated = True

Safe Migration

Migration preserves existing theme options:

# Safely update theme options without overwriting existing values
config.html_theme_options["new_option"] = raw["deprecated_option"]
del raw["deprecated_option"]

Maintenance and Evolution

Adding New Deprecated Options

To deprecate a new option:

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

Version Management

The extension tracks theme version for context:

from . import __version__

return {
    "version": __version__,
    "parallel_read_safe": True,
    "parallel_write_safe": True,
}

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

Install with Tessl CLI

npx tessl i tessl/pypi-sphinxawesome-theme

docs

code-highlighting.md

deprecated-options.md

html-postprocessing.md

index.md

json-serialization.md

logo-management.md

template-functions.md

theme-builder.md

theme-configuration.md

toc-manipulation.md

tile.json