0
# Theme System
1
2
Five pre-configured Sphinx themes providing consistent visual styling for Pallets projects. All themes inherit from the base `pocoo` theme and include project-specific stylesheets, Pygments syntax highlighting, and customized layouts.
3
4
## Capabilities
5
6
### Available Themes
7
8
Five themes are automatically registered when the extension loads, each designed for specific Pallets projects.
9
10
```python { .api }
11
# Theme configuration in conf.py
12
html_theme = "pocoo" # Base theme with pocoo styling
13
html_theme = "flask" # Flask project theme
14
html_theme = "jinja" # Jinja project theme
15
html_theme = "werkzeug" # Werkzeug project theme
16
html_theme = "click" # Click project theme
17
```
18
19
### Theme Detection
20
21
Automatic detection of whether the current theme is a Pallets theme, enabling theme-specific functionality.
22
23
```python { .api }
24
def set_is_pallets_theme(app):
25
"""
26
Set the is_pallets_theme config value based on current theme.
27
28
Detects if the current theme inherits from the pocoo theme by
29
checking theme directory hierarchy. Sets is_pallets_theme config
30
to True/False accordingly.
31
32
Parameters:
33
- app: Sphinx application instance
34
"""
35
```
36
37
### Theme-Specific Decorator
38
39
Decorator factory for creating functions that only execute when using a Pallets theme.
40
41
```python { .api }
42
def only_pallets_theme(default=None):
43
"""
44
Create decorator that executes function only with Pallets themes.
45
46
Used to prevent Sphinx event callbacks from running when Pallets
47
themes are installed but not active.
48
49
Parameters:
50
- default: Value to return if not using a Pallets theme
51
52
Returns:
53
function: Decorator that wraps the target function
54
"""
55
```
56
57
## Theme Details
58
59
### Pocoo Theme (Base)
60
61
The foundational theme that all other Pallets themes inherit from.
62
63
**Configuration:**
64
- Inherits from: Sphinx `basic` theme
65
- Stylesheet: `pocoo.css`
66
- Pygments style: `pocoo`
67
- Sidebars: `localtoc.html`, `relations.html`, `searchbox.html`, `ethicalads.html`
68
- Options: `index_sidebar_logo = True`
69
70
**Templates included:**
71
- `layout.html` - Main page layout
72
- `localtoc.html` - Local table of contents
73
- `relations.html` - Previous/next navigation
74
- `project.html` - Project information
75
- `ethicalads.html` - Ethical advertising integration
76
77
**JavaScript:**
78
- `describe_version.js` - Version warning banner functionality
79
80
### Flask Theme
81
82
Customized theme for Flask project documentation.
83
84
**Configuration:**
85
- Inherits from: `pocoo`
86
- Stylesheet: `flask.css`
87
- Pygments style: Inherits from pocoo
88
89
### Jinja Theme
90
91
Customized theme for Jinja project documentation with specialized syntax highlighting.
92
93
**Configuration:**
94
- Inherits from: `pocoo`
95
- Stylesheet: `jinja.css`
96
- Pygments style: `jinja` (custom JinjaStyle class)
97
98
### Click Theme
99
100
Customized theme for Click project documentation.
101
102
**Configuration:**
103
- Inherits from: `pocoo`
104
- Stylesheet: `click.css`
105
- Pygments style: `tango`
106
107
### Werkzeug Theme
108
109
Customized theme for Werkzeug project documentation.
110
111
**Configuration:**
112
- Inherits from: `pocoo`
113
- Stylesheet: `werkzeug.css`
114
- Pygments style: Inherits from pocoo
115
116
## Usage Examples
117
118
### Basic Theme Selection
119
120
Configure your theme in `conf.py`:
121
122
```python
123
# Select a theme
124
html_theme = "flask"
125
126
# Optional: Override theme-specific settings
127
html_theme_options = {
128
"index_sidebar_logo": False # For pocoo-based themes
129
}
130
```
131
132
### Theme-Aware Functionality
133
134
Create functions that only run with Pallets themes:
135
136
```python
137
from pallets_sphinx_themes.theme_check import only_pallets_theme
138
139
@only_pallets_theme()
140
def add_custom_css(app):
141
"""Add custom CSS only when using Pallets themes."""
142
app.add_css_file("custom-pallets.css")
143
144
@only_pallets_theme(default="Not using Pallets theme")
145
def get_theme_status(app):
146
"""Return theme-specific message."""
147
return f"Using Pallets theme: {app.builder.theme.name}"
148
149
def setup(app):
150
app.connect("builder-inited", add_custom_css)
151
```
152
153
### Conditional Configuration
154
155
Configure different behavior based on theme detection:
156
157
```python
158
# conf.py
159
extensions = ["pallets_sphinx_themes"]
160
html_theme = "flask"
161
162
# This will be auto-set to True after theme detection
163
if html_theme in ["pocoo", "flask", "jinja", "werkzeug", "click"]:
164
# Pallets-specific configuration
165
version_banner = True
166
rtd_canonical_path = "/en/stable/"
167
else:
168
# Non-Pallets theme configuration
169
version_banner = False
170
```
171
172
### Pygments Style Configuration
173
174
The themes automatically set appropriate Pygments styles, but you can override:
175
176
```python
177
# Automatic (recommended):
178
html_theme = "jinja" # Automatically uses "jinja" pygments style
179
html_theme = "click" # Automatically uses "tango" pygments style
180
181
# Manual override:
182
html_theme = "flask"
183
pygments_style = "pocoo" # Override to use pocoo style instead
184
```
185
186
## Configuration Values
187
188
Theme-related configuration values available in `conf.py`:
189
190
```python { .api }
191
# Theme selection
192
html_theme = "flask" # str: Theme name ("pocoo", "flask", "jinja", "werkzeug", "click")
193
194
# Auto-detected theme status (set by extension)
195
is_pallets_theme = None # bool or None: True when using any Pallets theme
196
197
# Theme-specific options (pocoo base theme)
198
html_theme_options = {
199
"index_sidebar_logo": True # bool: Show logo in index sidebar
200
}
201
202
# Version banner (theme-aware)
203
version_banner = True # bool: Enable version warning banner
204
205
# Canonical path for Read the Docs (theme-aware)
206
rtd_canonical_path = "/en/stable/" # str: Default canonical path
207
```