0
# Pallets Sphinx Themes
1

2
Sphinx themes for Pallets and related projects, providing consistent visual styling and specialized documentation directives for Flask, Jinja, Werkzeug, and Click projects. This package extends Sphinx with professionally designed themes and domain-specific directives for enhanced technical documentation.
3

4
## Package Information
5

6
- **Package Name**: Pallets-Sphinx-Themes
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pallets-sphinx-themes`
10

11
## Core Imports
12

13
```python
14
import pallets_sphinx_themes
15
```
16

17
For version utilities:
18

19
```python
20
from pallets_sphinx_themes import get_version
21
```
22

23
## Basic Usage
24

25
Add the extension to your Sphinx `conf.py`:
26

27
```python
28
extensions = [
29
    "pallets_sphinx_themes",
30
    # ... other extensions
31
]
32

33
# Choose from available themes: flask, jinja, werkzeug, click, pocoo
34
html_theme = "flask"
35
```
36

37
Get version information for your project:
38

39
```python
40
from pallets_sphinx_themes import get_version
41

42
release, version = get_version("MyProject")
43
# release = "1.0.3.dev0", version = "1.0.x"
44
```
45

46
## Architecture
47

48
The package follows a modular architecture:
49

50
- **Main Extension**: Core Sphinx extension providing theme registration and configuration
51
- **Theme System**: Five themes (pocoo base theme + flask, jinja, werkzeug, click variants)
52
- **Domain Extensions**: Specialized Sphinx domains for Click and Jinja documentation
53
- **Theme Detection**: Automatic detection and configuration for Pallets-specific features
54
- **Utility Functions**: Version handling and project configuration helpers
55

56
All themes inherit from the base `pocoo` theme which provides consistent layout, styling, and documentation features across the Pallets ecosystem.
57

58
## Capabilities
59

60
### Core Extension Setup
61

62
Main Sphinx extension providing theme registration, configuration values, and integration with Sphinx's build system. Handles automatic theme detection and applies Pallets-specific enhancements.
63

64
```python { .api }
65
def setup(app):
66
    """
67
    Register themes and configure Sphinx application.
68
    
69
    Parameters:
70
    - app: Sphinx application instance
71
    
72
    Returns:
73
    dict: Extension metadata with version and parallel_read_safe info
74
    """
75
```
76

77
[Core Extension](./core-extension.md)
78

79
### Theme System
80

81
Five pre-configured Sphinx themes providing consistent visual styling for Pallets projects. Includes base pocoo theme and project-specific variants with custom stylesheets and Pygments syntax highlighting.
82

83
```python { .api }
84
# Configuration values available in conf.py
85
is_pallets_theme: bool  # Auto-detected, indicates if using Pallets theme
86
rtd_canonical_path: str  # Canonical path for Read the Docs (default: "/en/stable/")
87
version_banner: bool  # Enable version warning banner (default: True)
88
```
89

90
Available themes: `pocoo`, `flask`, `jinja`, `werkzeug`, `click`
91

92
[Theme System](./theme-system.md)
93

94
### Click Domain
95

96
Specialized Sphinx domain providing directives for documenting Click command-line applications. Enables interactive command examples with automatic input/output capture and syntax highlighting.
97

98
```python { .api }
99
# Available directives in rst files
100
# .. click:example::
101
#    Python code defining Click commands
102
#
103
# .. click:run::
104
#    Commands to execute and display output
105
```
106

107
[Click Domain](./click-domain.md)
108

109
### Jinja Domain
110

111
Specialized Sphinx domain for documenting Jinja2 templates, filters, tests, and node classes. Automatically generates comprehensive API documentation from Jinja mappings and class hierarchies.
112

113
```python { .api }
114
# Available directives in rst files
115
# .. jinja:filters:: module.path.to.filters_dict
116
# .. jinja:tests:: module.path.to.tests_dict  
117
# .. jinja:nodes:: module.path.to.base_node_class
118
```
119

120
[Jinja Domain](./jinja-domain.md)
121

122
### Utility Functions
123

124
Helper functions for version management and project configuration in Sphinx documentation projects.
125

126
```python { .api }
127
def get_version(name: str, version_length: int = 2, placeholder: str = "x") -> tuple[str, str]:
128
    """
129
    Get version information for Sphinx documentation.
130
    
131
    Parameters:
132
    - name: Package name to get version for
133
    - version_length: Number of version components to include in short version
134
    - placeholder: Placeholder for additional version components
135
    
136
    Returns:
137
    tuple: (release, version) where release is full version, version is abbreviated
138
    """
139
```
140

141
[Utilities](./utilities.md)
142

143
## Configuration Values
144

145
The extension adds these configuration values to Sphinx:
146

147
```python { .api }
148
# In conf.py
149
is_pallets_theme = None  # Auto-detected boolean, True if using Pallets theme
150
rtd_canonical_path = "/en/stable/"  # Canonical path for Read the Docs
151
version_banner = True  # Enable version warning banner
152
```
153

154
## Theme Detection
155

156
The package automatically detects whether you're using a Pallets theme and enables appropriate features:
157

158
```python { .api }
159
from pallets_sphinx_themes.theme_check import only_pallets_theme
160

161
@only_pallets_theme()
162
def my_pallets_specific_function(app):
163
    """Function only runs when using a Pallets theme."""
164
    pass
165
```
166

167
## Types
168

169
```python { .api }
170
from collections import namedtuple
171

172
ProjectLink = namedtuple("ProjectLink", ("title", "url"))
173
# Named tuple for project links with title and url fields
174
```