Theme Setup and Configuration

def setup(app: Sphinx) -> Dict[str, str]:
    """
    Setup the Sphinx application.
    
    This is the main entry point that:
    - Registers the HTML theme with Sphinx
    - Adds post-transforms for link processing
    - Connects event handlers for configuration and template processing
    - Sets up message catalogs for internationalization
    - Configures template paths
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    
    Returns:
    Dict[str, str]: Extension metadata with parallel read/write safety flags
    """

def update_config(app):
    """
    Update config with new default values and handle deprecated keys.
    
    This function:
    - Handles deprecated pygments style key names
    - Validates icon_links configuration format
    - Sets default permalink icons if not provided by user
    - Validates and processes theme switcher configuration
    - Adds analytics scripts (Google Analytics and Plausible)
    - Configures ABlog integration if present
    - Processes icon link shortcuts for common platforms
    - Prepares logo configuration dictionary
    
    Parameters:
    - app: Sphinx application instance with theme options
    
    Raises:
    - ExtensionError: If icon_links is not a list or logo config is invalid
    """

# This happens automatically when Sphinx loads the theme
html_theme = "pydata_sphinx_theme"

# conf.py
html_theme = "pydata_sphinx_theme"
html_theme_options = {
    # Logo configuration
    "logo": {
        "image_light": "logo-light.png",
        "image_dark": "logo-dark.png", 
        "text": "My Project",
        "link": "https://myproject.org"
    },
    
    # Icon links in header
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/user/repo",
            "icon": "fa-brands fa-square-github",
            "type": "fontawesome",
        },
        {
            "name": "PyPI",
            "url": "https://pypi.org/project/mypackage/",
            "icon": "fa-custom fa-pypi",
            "type": "fontawesome",
        }
    ],
    
    # Analytics integration
    "analytics": {
        "google_analytics_id": "G-XXXXXXXXXX",
        "plausible_analytics_domain": "mysite.com",
        "plausible_analytics_url": "https://plausible.io/js/script.js"
    },
    
    # Theme switcher
    "switcher": {
        "json_url": "https://mysite.com/switcher.json",
        "version_match": "0.1.0"
    },
    
    # Pygments styling
    "pygments_light_style": "github-light",
    "pygments_dark_style": "github-dark",
    
    # Navigation
    "show_toc_level": 2,
    "navbar_align": "left",
    "show_nav_level": 1,
    
    # Footer
    "footer_start": ["copyright"],
    "footer_center": ["sphinx-version"],
    "footer_end": ["theme-version"]
}

# Deprecated shortcuts (still supported)
html_theme_options = {
    "github_url": "https://github.com/user/repo",  # Converted to icon_links
    "twitter_url": "https://twitter.com/user",    # Converted to icon_links
}

# Icon links support multiple types and configurations
html_theme_options = {
    "icon_links": [
        # FontAwesome icons
        {
            "name": "GitHub",
            "url": "https://github.com/user/repo", 
            "icon": "fa-brands fa-github",
            "type": "fontawesome"
        },
        
        # Local image icons
        {
            "name": "Custom Service",
            "url": "https://service.com",
            "icon": "_static/service-icon.png", 
            "type": "local"
        },
        
        # URL-based icons
        {
            "name": "External Service",
            "url": "https://external.com",
            "icon": "https://external.com/icon.png",
            "type": "url"
        }
    ]
}

# Google Analytics setup
html_theme_options = {
    "analytics": {
        "google_analytics_id": "G-XXXXXXXXXX"
    }
}

# Plausible Analytics setup  
html_theme_options = {
    "analytics": {
        "plausible_analytics_domain": "mysite.com",
        "plausible_analytics_url": "https://plausible.io/js/script.js"
    }
}

# Both analytics services
html_theme_options = {
    "analytics": {
        "google_analytics_id": "G-XXXXXXXXXX",
        "plausible_analytics_domain": "mysite.com", 
        "plausible_analytics_url": "https://plausible.io/js/script.js"
    }
}