0
# Utilities
1

2
Helper functions for version management, project configuration, and theme detection in Sphinx documentation projects. These utilities support common documentation workflows and integration patterns.
3

4
## Capabilities
5

6
### Version Management
7

8
Utility function for retrieving and formatting package version information for Sphinx documentation.
9

10
```python { .api }
11
def get_version(name, version_length=2, placeholder="x"):
12
    """
13
    Get version information for Sphinx documentation.
14
    
15
    Ensures the named package is installed and returns properly formatted
16
    version strings for use in Sphinx conf.py. Creates both a full release
17
    version and an abbreviated version suitable for documentation display.
18
    
19
    Parameters:
20
    - name (str): Name of package to get version information for
21
    - version_length (int): Number of version components to include in abbreviated version (default: 2)  
22
    - placeholder (str): Placeholder suffix for abbreviated version (default: "x")
23
    
24
    Returns:
25
    tuple[str, str]: (release, version) where:
26
        - release: Full version string (e.g., "1.0.3.dev0")  
27
        - version: Abbreviated version (e.g., "1.0.x")
28
    
29
    Raises:
30
    SystemExit: If the specified package is not installed
31
    """
32
```
33

34
### Theme Detection
35

36
Functions for detecting and managing Pallets theme usage.
37

38
```python { .api }
39
def set_is_pallets_theme(app):
40
    """
41
    Detect and configure Pallets theme usage.
42
    
43
    Examines the current Sphinx theme to determine if it inherits from
44
    the pocoo theme, setting the is_pallets_theme configuration value
45
    accordingly. This enables conditional theme-specific functionality.
46
    
47
    Parameters:
48
    - app: Sphinx application instance
49
    """
50

51
def only_pallets_theme(default=None):
52
    """
53
    Create decorator for theme-conditional functions.
54
    
55
    Returns a decorator that ensures the wrapped function only executes
56
    when using a Pallets theme. Used to prevent Sphinx event callbacks
57
    from running when Pallets themes are installed but not active.
58
    
59
    Parameters:
60
    - default: Value to return if not using a Pallets theme (default: None)
61
    
62
    Returns:
63
    function: Decorator that wraps target functions with theme checking
64
    """
65
```
66

67
### Data Structures
68

69
Named tuple for representing project links in documentation.
70

71
```python { .api }
72
ProjectLink = namedtuple("ProjectLink", ("title", "url"))
73
"""
74
Named tuple for project links.
75

76
Fields:
77
- title (str): Display title for the link
78
- url (str): URL target for the link
79

80
Used for rendering consistent project links in Sphinx themes.
81
"""
82
```
83

84
## Usage Examples
85

86
### Version Configuration
87

88
Use `get_version()` in your Sphinx `conf.py` to automatically manage version strings:
89

90
```python
91
# conf.py
92
from pallets_sphinx_themes import get_version
93

94
# Get version for your project
95
release, version = get_version("MyProject")
96
# release = "2.1.3.dev0", version = "2.1.x"
97

98
# Custom version formatting
99
release, version = get_version("MyProject", version_length=3, placeholder="dev")
100
# release = "2.1.3.dev0", version = "2.1.3.dev"
101

102
# Single component version
103
release, version = get_version("MyProject", version_length=1, placeholder="")
104
# release = "2.1.3.dev0", version = "2"
105
```
106

107
### Theme-Conditional Configuration
108

109
Create configuration that adapts based on theme detection:
110

111
```python
112
from pallets_sphinx_themes.theme_check import only_pallets_theme
113

114
@only_pallets_theme()
115
def setup_pallets_features(app):
116
    """Configure features specific to Pallets themes."""
117
    app.add_css_file("pallets-custom.css")
118
    app.config.html_show_sourcelink = False
119

120
@only_pallets_theme(default="Generic theme in use")
121
def get_theme_message(app):
122
    """Get theme-specific message."""
123
    return f"Using Pallets theme: {app.builder.theme.name}"
124

125
def setup(app):
126
    app.connect("builder-inited", setup_pallets_features)
127
```
128

129
### Project Links
130

131
Use `ProjectLink` for consistent link formatting:
132

133
```python
134
from pallets_sphinx_themes import ProjectLink
135

136
# Create project links
137
docs_link = ProjectLink("Documentation", "https://example.com/docs")
138
github_link = ProjectLink("Source Code", "https://github.com/user/project")
139

140
# Use in templates or configuration
141
project_links = [docs_link, github_link]
142

143
# Access fields
144
print(f"Visit {docs_link.title} at {docs_link.url}")
145
```
146

147
### Error Handling
148

149
Handle missing packages gracefully:
150

151
```python
152
try:
153
    from pallets_sphinx_themes import get_version
154
    release, version = get_version("MyOptionalDependency")
155
except SystemExit:
156
    # Package not installed, use fallback
157
    release = "unknown"
158
    version = "dev"
159
    print("Warning: MyOptionalDependency not found, using fallback version")
160
```
161

162
### Integration with Sphinx Events
163

164
Use utilities in Sphinx event handlers:
165

166
```python
167
from pallets_sphinx_themes.theme_check import only_pallets_theme
168

169
@only_pallets_theme()
170
def add_version_info(app, pagename, templatename, context, doctree):
171
    """Add version information to page context."""
172
    if app.config.project:
173
        try:
174
            release, version = get_version(app.config.project)
175
            context['project_release'] = release
176
            context['project_version'] = version
177
        except SystemExit:
178
            context['project_release'] = "unknown"
179
            context['project_version'] = "dev"
180

181
def setup(app):
182
    app.connect("html-page-context", add_version_info)
183
```
184

185
### Conditional Extension Loading
186

187
Use theme detection to conditionally load extensions:
188

189
```python
190
# conf.py
191
extensions = ["pallets_sphinx_themes"]
192

193
# After extension loads, is_pallets_theme will be set
194
def setup(app):
195
    @only_pallets_theme()
196
    def load_pallets_extensions(app):
197
        """Load additional extensions for Pallets themes."""
198
        if "sphinx_design" not in app.config.extensions:
199
            app.config.extensions.append("sphinx_design")
200
        if "sphinx_copybutton" not in app.config.extensions:
201
            app.config.extensions.append("sphinx_copybutton")
202
    
203
    app.connect("builder-inited", load_pallets_extensions)
204
```
205

206
## Version String Examples
207

208
The `get_version()` function produces version strings in this format:
209

210
```python
211
# Example version strings for different inputs:
212

213
# Package version: "1.2.3"
214
get_version("pkg")           # ("1.2.3", "1.2.x")
215
get_version("pkg", 1)        # ("1.2.3", "1.x") 
216
get_version("pkg", 3)        # ("1.2.3", "1.2.3.x")
217
get_version("pkg", 2, "dev") # ("1.2.3", "1.2.dev")
218

219
# Package version: "2.0.1.post1"  
220
get_version("pkg")           # ("2.0.1.post1", "2.0.x")
221
get_version("pkg", 3)        # ("2.0.1.post1", "2.0.1.x")
222

223
# Package version: "1.0.0a1"
224
get_version("pkg")           # ("1.0.0a1", "1.0.x")
225
get_version("pkg", 3, "")    # ("1.0.0a1", "1.0.0")
226
```