0
# Python Extension API
1

2
Core Sphinx extension functionality that registers the theme, validates configuration, and extends template context for Read the Docs integration.
3

4
## Capabilities
5

6
### Theme Setup and Registration
7

8
Main setup function that registers the sphinx_rtd_theme with Sphinx and configures all necessary components.
9

10
```python { .api }
11
def setup(app):
12
    """
13
    Main theme setup function called by Sphinx.
14
    
15
    Parameters:
16
    - app: Sphinx application instance
17
    
18
    Returns:
19
    dict: Extension metadata with parallel_read_safe and parallel_write_safe flags
20
    
21
    Actions:
22
    - Validates Python 3+ and Sphinx 6+ requirements  
23
    - Registers theme with Sphinx via app.add_html_theme()
24
    - Sets up message catalogs for internationalization support
25
    - Configures jQuery dependency via sphinxcontrib-jquery extension
26
    - Connects event handlers for configuration validation and context extension
27
    - Sets permalink icon to FontAwesome link icon (\uf0c1)
28
    """
29
```
30

31
**Usage Example:**
32

33
```python
34
# Theme is automatically registered via entry point in setup.cfg:
35
# [options.entry_points]
36
# sphinx.html_themes = 
37
#     sphinx_rtd_theme = sphinx_rtd_theme
38

39
# In conf.py:
40
html_theme = 'sphinx_rtd_theme'
41
```
42

43
### Theme Path Access
44

45
Provides access to theme directory path (deprecated function maintained for backwards compatibility).
46

47
```python { .api }
48
def get_html_theme_path():
49
    """
50
    Return list of HTML theme paths (deprecated).
51
    
52
    Returns:
53
    str: Absolute path to theme directory
54
    
55
    Status: Deprecated with warning message
56
    Note: Safe to remove calls to this function when defining html_theme_path
57
    """
58
```
59

60
### Configuration Validation
61

62
Validates theme configuration and warns about deprecated options.
63

64
```python { .api }
65
def config_initiated(app, config):
66
    """
67
    Sphinx event handler for configuration validation.
68
    
69
    Parameters:
70
    - app: Sphinx application instance
71
    - config: Sphinx configuration object
72
    
73
    Validates and warns about deprecated options:
74
    - canonical_url (use html_baseurl from Sphinx instead)
75
    - analytics_id (use sphinxcontrib-googleanalytics extension instead)
76
    - analytics_anonymize_ip (use sphinxcontrib-googleanalytics extension instead)
77
    - extra_css_file (use html_css_files from Sphinx instead)
78
    """
79
```
80

81
### Template Context Extension
82

83
Extends Jinja2 template context with theme-specific variables and Read the Docs environment detection.
84

85
```python { .api }
86
def extend_html_context(app, pagename, templatename, context, doctree):
87
    """
88
    Sphinx event handler for extending template context.
89
    
90
    Parameters:
91
    - app: Sphinx application instance
92
    - pagename: Current page name being rendered
93
    - templatename: Name of template being rendered
94
    - context: Template context dictionary (modified in-place)
95
    - doctree: Document tree for current page
96
    
97
    Adds to context:
98
    - sphinx_version_info: Sphinx version tuple for template conditionals
99
    - READTHEDOCS: Boolean indicating Read the Docs environment
100
    - READTHEDOCS_*: All Read the Docs environment variables
101
    """
102
```
103

104
**Template Context Variables:**
105

106
```python { .api }
107
# Available in all templates after context extension:
108
{
109
    'sphinx_version_info': tuple,  # e.g. (7, 1, 2)
110
    'READTHEDOCS': bool,           # True if building on Read the Docs
111
    'READTHEDOCS_VERSION': str,    # RTD version identifier (if applicable)
112
    'READTHEDOCS_PROJECT': str,    # RTD project name (if applicable)
113
    'READTHEDOCS_LANGUAGE': str,   # RTD language code (if applicable)
114
    # ... additional READTHEDOCS_* variables as available
115
}
116
```
117

118
## Module Constants
119

120
```python { .api }
121
__version__ = "3.0.2"
122
__version_full__ = "3.0.2" 
123
logger = getLogger(__name__)  # Package logger instance
124
```
125

126
## Entry Point Registration
127

128
```python { .api }
129
# Automatic registration via setup.cfg:
130
[options.entry_points]
131
sphinx.html_themes = 
132
    sphinx_rtd_theme = sphinx_rtd_theme
133
```
134

135
## Error Handling
136

137
The setup function performs validation and raises errors for:
138

139
- **Python version**: Requires Python 3+
140
- **Sphinx version**: Requires Sphinx 6.0+  
141
- **HTML4 writer**: Not supported, raises error if html4_writer is enabled
142
- **jQuery dependency**: Automatically adds sphinxcontrib-jquery for Sphinx 6+
143

144
## Usage Examples
145

146
### Basic Theme Usage
147

148
```python
149
# In Sphinx conf.py - theme is automatically available
150
html_theme = 'sphinx_rtd_theme'
151
```
152

153
### Advanced Setup Integration
154

155
```python
156
# Custom extension that uses theme functions
157
def my_setup(app):
158
    # Access theme path (though not typically needed)
159
    theme_path = sphinx_rtd_theme.get_html_theme_path()
160
    
161
    # The theme's setup function handles all necessary registration
162
    # No manual theme registration needed due to entry point
163
    
164
    return {'version': '1.0', 'parallel_read_safe': True}
165
```
166

167
### Environment Detection
168

169
```python
170
# In Jinja2 templates, after context extension:
171
{% if READTHEDOCS %}
172
    <div class="rtd-environment">
173
        Building on Read the Docs: {{ READTHEDOCS_VERSION }}
174
    </div>
175
{% endif %}
176

177
{% if sphinx_version_info >= (7, 0, 0) %}
178
    <!-- Use Sphinx 7+ features -->
179
{% endif %}
180
```