0
# Theme Setup and Configuration
1

2
Core functionality for registering the PyData Sphinx Theme with Sphinx and managing configuration options, including theme options validation, deprecated key handling, and analytics integration.
3

4
## Capabilities
5

6
### Theme Registration
7

8
Registers the theme with Sphinx's extension system and sets up all event handlers and configuration.
9

10
```python { .api }
11
def setup(app: Sphinx) -> Dict[str, str]:
12
    """
13
    Setup the Sphinx application.
14
    
15
    This is the main entry point that:
16
    - Registers the HTML theme with Sphinx
17
    - Adds post-transforms for link processing
18
    - Connects event handlers for configuration and template processing
19
    - Sets up message catalogs for internationalization
20
    - Configures template paths
21
    
22
    Parameters:
23
    - app (Sphinx): The Sphinx application instance
24
    
25
    Returns:
26
    Dict[str, str]: Extension metadata with parallel read/write safety flags
27
    """
28
```
29

30
### Configuration Management
31

32
Updates and validates theme configuration options, handling deprecated keys and setting defaults.
33

34
```python { .api }
35
def update_config(app):
36
    """
37
    Update config with new default values and handle deprecated keys.
38
    
39
    This function:
40
    - Handles deprecated pygments style key names
41
    - Validates icon_links configuration format
42
    - Sets default permalink icons if not provided by user
43
    - Validates and processes theme switcher configuration
44
    - Adds analytics scripts (Google Analytics and Plausible)
45
    - Configures ABlog integration if present
46
    - Processes icon link shortcuts for common platforms
47
    - Prepares logo configuration dictionary
48
    
49
    Parameters:
50
    - app: Sphinx application instance with theme options
51
    
52
    Raises:
53
    - ExtensionError: If icon_links is not a list or logo config is invalid
54
    """
55
```
56

57
## Usage Examples
58

59
### Basic Theme Registration
60

61
```python
62
# This happens automatically when Sphinx loads the theme
63
html_theme = "pydata_sphinx_theme"
64
```
65

66
### Advanced Configuration
67

68
```python
69
# conf.py
70
html_theme = "pydata_sphinx_theme"
71
html_theme_options = {
72
    # Logo configuration
73
    "logo": {
74
        "image_light": "logo-light.png",
75
        "image_dark": "logo-dark.png", 
76
        "text": "My Project",
77
        "link": "https://myproject.org"
78
    },
79
    
80
    # Icon links in header
81
    "icon_links": [
82
        {
83
            "name": "GitHub",
84
            "url": "https://github.com/user/repo",
85
            "icon": "fa-brands fa-square-github",
86
            "type": "fontawesome",
87
        },
88
        {
89
            "name": "PyPI",
90
            "url": "https://pypi.org/project/mypackage/",
91
            "icon": "fa-custom fa-pypi",
92
            "type": "fontawesome",
93
        }
94
    ],
95
    
96
    # Analytics integration
97
    "analytics": {
98
        "google_analytics_id": "G-XXXXXXXXXX",
99
        "plausible_analytics_domain": "mysite.com",
100
        "plausible_analytics_url": "https://plausible.io/js/script.js"
101
    },
102
    
103
    # Theme switcher
104
    "switcher": {
105
        "json_url": "https://mysite.com/switcher.json",
106
        "version_match": "0.1.0"
107
    },
108
    
109
    # Pygments styling
110
    "pygments_light_style": "github-light",
111
    "pygments_dark_style": "github-dark",
112
    
113
    # Navigation
114
    "show_toc_level": 2,
115
    "navbar_align": "left",
116
    "show_nav_level": 1,
117
    
118
    # Footer
119
    "footer_start": ["copyright"],
120
    "footer_center": ["sphinx-version"],
121
    "footer_end": ["theme-version"]
122
}
123

124
# Deprecated shortcuts (still supported)
125
html_theme_options = {
126
    "github_url": "https://github.com/user/repo",  # Converted to icon_links
127
    "twitter_url": "https://twitter.com/user",    # Converted to icon_links
128
}
129
```
130

131
### Icon Links Configuration
132

133
```python
134
# Icon links support multiple types and configurations
135
html_theme_options = {
136
    "icon_links": [
137
        # FontAwesome icons
138
        {
139
            "name": "GitHub",
140
            "url": "https://github.com/user/repo", 
141
            "icon": "fa-brands fa-github",
142
            "type": "fontawesome"
143
        },
144
        
145
        # Local image icons
146
        {
147
            "name": "Custom Service",
148
            "url": "https://service.com",
149
            "icon": "_static/service-icon.png", 
150
            "type": "local"
151
        },
152
        
153
        # URL-based icons
154
        {
155
            "name": "External Service",
156
            "url": "https://external.com",
157
            "icon": "https://external.com/icon.png",
158
            "type": "url"
159
        }
160
    ]
161
}
162
```
163

164
### Analytics Configuration
165

166
```python
167
# Google Analytics setup
168
html_theme_options = {
169
    "analytics": {
170
        "google_analytics_id": "G-XXXXXXXXXX"
171
    }
172
}
173

174
# Plausible Analytics setup  
175
html_theme_options = {
176
    "analytics": {
177
        "plausible_analytics_domain": "mysite.com",
178
        "plausible_analytics_url": "https://plausible.io/js/script.js"
179
    }
180
}
181

182
# Both analytics services
183
html_theme_options = {
184
    "analytics": {
185
        "google_analytics_id": "G-XXXXXXXXXX",
186
        "plausible_analytics_domain": "mysite.com", 
187
        "plausible_analytics_url": "https://plausible.io/js/script.js"
188
    }
189
}
190
```
191

192
## Configuration Validation
193

194
The theme validates several configuration options:
195

196
- **icon_links**: Must be a list of dictionaries
197
- **logo**: Must be a dictionary if provided  
198
- **switcher**: Must contain `json_url` and `version_match` keys if provided
199
- **analytics**: Validates analytics service configurations
200

201
Invalid configurations will raise `ExtensionError` exceptions during Sphinx initialization.