0
# Core Extension
1

2
The main Sphinx extension that provides theme registration, configuration management, and integration with Sphinx's build system. This extension serves as the entry point for all Pallets Sphinx Themes functionality.
3

4
## Capabilities
5

6
### Extension Setup
7

8
The primary setup function that registers themes, configuration values, and event handlers with Sphinx.
9

10
```python { .api }
11
def setup(app):
12
    """
13
    Register Pallets themes and configure Sphinx application.
14
    
15
    Automatically discovers and registers all themes in the themes directory,
16
    adds configuration values, configures sphinx-notfound-page extension,
17
    and connects event handlers for theme-specific functionality.
18
    
19
    Parameters:
20
    - app: Sphinx application instance
21
    
22
    Returns:
23
    dict: Extension metadata containing version and parallel_read_safe status
24
    """
25
```
26

27
### Event Handlers
28

29
Functions that respond to Sphinx build events to provide theme-specific enhancements.
30

31
```python { .api }
32
def find_base_canonical_url(app):
33
    """
34
    Configure canonical URL from Read the Docs environment.
35
    
36
    When building on Read the Docs, constructs the base canonical URL from
37
    environment variables if not explicitly configured. Only active when
38
    using a Pallets theme.
39
    
40
    Parameters:
41
    - app: Sphinx application instance
42
    """
43

44
def add_theme_files(app):
45
    """
46
    Add theme-specific JavaScript files and version banners.
47
    
48
    Conditionally includes version warning JavaScript based on build
49
    environment and configuration. Only active when using a Pallets theme.
50
    
51
    Parameters:
52
    - app: Sphinx application instance
53
    """
54

55
def canonical_url(app, pagename, templatename, context, doctree):
56
    """
57
    Fix canonical URLs for dirhtml builder.
58
    
59
    Corrects canonical URL generation when using Sphinx's dirhtml builder
60
    to avoid incorrect .html suffixes. Only active when using a Pallets theme.
61
    
62
    Parameters:
63
    - app: Sphinx application instance
64
    - pagename: Name of the page being processed
65
    - templatename: Template being used
66
    - context: Template context dictionary
67
    - doctree: Document tree being processed
68
    """
69
```
70

71
### Autodoc Integration
72

73
Functions that enhance Sphinx's autodoc functionality for Pallets projects.
74

75
```python { .api }
76
def skip_internal(app, what, name, obj, skip, options):
77
    """
78
    Skip autodoc rendering for internal-only objects.
79
    
80
    Skips rendering when an object's docstring contains a line with only
81
    the string ':internal:'. Only active when using a Pallets theme.
82
    
83
    Parameters:
84
    - app: Sphinx application instance
85
    - what: Type of object being documented
86
    - name: Name of the object
87
    - obj: The object itself
88
    - skip: Current skip status
89
    - options: Autodoc options
90
    
91
    Returns:
92
    bool or None: True to skip, None to use default behavior
93
    """
94

95
def cut_module_meta(app, what, name, obj, options, lines):
96
    """
97
    Remove copyright and license lines from module documentation.
98
    
99
    Filters out lines starting with ':copyright:' or ':license:' from
100
    module autodoc to reduce noise in generated documentation.
101
    Only active when using a Pallets theme.
102
    
103
    Parameters:
104
    - app: Sphinx application instance
105
    - what: Type of object being documented
106
    - name: Name of the object
107
    - obj: The object itself
108
    - options: Autodoc options
109
    - lines: List of docstring lines (modified in place)
110
    """
111
```
112

113
## Usage Examples
114

115
### Basic Extension Setup
116

117
Add the extension to your Sphinx configuration:
118

119
```python
120
# conf.py
121
extensions = [
122
    "pallets_sphinx_themes",
123
    # ... other extensions
124
]
125

126
# Select a theme
127
html_theme = "flask"  # or "jinja", "werkzeug", "click", "pocoo"
128

129
# Optional: Configure canonical path for Read the Docs
130
rtd_canonical_path = "/en/latest/"
131

132
# Optional: Disable version banner
133
version_banner = False
134
```
135

136
### Event Handler Registration
137

138
The extension automatically registers event handlers, but you can also register custom handlers that respect theme detection:
139

140
```python
141
from pallets_sphinx_themes.theme_check import only_pallets_theme
142

143
@only_pallets_theme()
144
def my_custom_handler(app):
145
    """Custom handler that only runs with Pallets themes."""
146
    # Your custom functionality here
147
    pass
148

149
def setup(app):
150
    app.connect("builder-inited", my_custom_handler)
151
```
152

153
### sphinx-notfound-page Integration
154

155
The extension automatically configures the sphinx-notfound-page extension if not already configured:
156

157
```python
158
# Automatic configuration (when extension loads):
159
app.config.extensions.append("notfound.extension")
160
app.config.notfound_context = {
161
    "title": "Page Not Found", 
162
    "body": "The page you requested does not exist..."
163
}
164

165
# Outside Read the Docs, disables URL prefix:
166
if "READTHEDOCS" not in os.environ:
167
    app.config.notfound_urls_prefix = None
168
```
169

170
## Configuration Values
171

172
The extension adds these configuration values that can be set in `conf.py`:
173

174
```python { .api }
175
# Theme detection (auto-set, can be overridden)
176
is_pallets_theme = None  # bool or None
177

178
# Read the Docs canonical path
179
rtd_canonical_path = "/en/stable/"  # str
180

181
# Version banner control  
182
version_banner = True  # bool
183
```