0
# Sphinx RTD Theme
1

2
A responsive and mobile-friendly Sphinx documentation theme designed primarily for Read the Docs but compatible with any Sphinx project. The theme combines Python packaging with JavaScript/CSS build tools to deliver a comprehensive documentation theme with excellent readability on both desktop and mobile devices.
3

4
## Package Information
5

6
- **Package Name**: sphinx-rtd-theme
7
- **Package Type**: pypi
8
- **Language**: Python (with JavaScript components)
9
- **Installation**: `pip install sphinx-rtd-theme`
10

11
## Core Imports
12

13
```python
14
import sphinx_rtd_theme
15
```
16

17
For accessing theme configuration functions:
18

19
```python
20
from sphinx_rtd_theme import get_html_theme_path, setup
21
```
22

23
## Basic Usage
24

25
### Theme Registration
26

27
Add to your Sphinx `conf.py`:
28

29
```python
30
# Register theme (automatic via entry point)
31
html_theme = 'sphinx_rtd_theme'
32

33
# Optional theme options
34
html_theme_options = {
35
    'collapse_navigation': True,
36
    'sticky_navigation': True,
37
    'navigation_depth': 4,
38
    'includehidden': True,
39
    'titles_only': False
40
}
41
```
42

43
### Manual Theme Setup (Advanced Usage)
44

45
```python
46
import sphinx_rtd_theme
47

48
def setup(app):
49
    # Add theme path manually (not typically needed)
50
    app.add_html_theme('sphinx_rtd_theme', sphinx_rtd_theme.get_html_theme_path())
51
    
52
    # Theme is automatically registered via entry point:
53
    # sphinx.html_themes = sphinx_rtd_theme = sphinx_rtd_theme
54
```
55

56
## Architecture
57

58
The theme consists of four main components:
59

60
- **Python Extension**: Sphinx theme registration, configuration validation, and template context extension
61
- **HTML Templates**: Complete Jinja2 template set for documentation rendering (layout, navigation, search, footer)
62
- **JavaScript Navigation**: Interactive ThemeNav class providing responsive navigation and mobile support
63
- **Static Assets**: CSS/SCSS styling and compiled JavaScript for responsive design
64

65
This modular architecture enables the theme to function as both a traditional Sphinx theme and a modern responsive web interface, with automatic jQuery integration, internationalization support, and Read the Docs environment detection.
66

67
## Capabilities
68

69
### Python Extension API
70

71
Core Sphinx extension functionality including theme registration, configuration validation with deprecation warnings, and template context extension for Read the Docs integration.
72

73
```python { .api }
74
def setup(app): ...
75
def get_html_theme_path(): ...
76
def config_initiated(app, config): ...
77
def extend_html_context(app, pagename, templatename, context, doctree): ...
78
```
79

80
[Python Extension](./python-extension.md)
81

82
### Theme Configuration
83

84
Comprehensive theme configuration system with 19 configurable options controlling navigation behavior, styling, and feature toggles including sticky navigation, collapsible menus, and responsive design settings.
85

86
```python { .api }
87
# Theme options for html_theme_options in conf.py
88
{
89
    'collapse_navigation': bool,
90
    'sticky_navigation': bool,
91
    'navigation_depth': int,
92
    'includehidden': bool,
93
    'titles_only': bool,
94
    'logo_only': bool,
95
    'prev_next_buttons_location': str,
96
    'style_external_links': bool,
97
    'flyout_display': str,
98
    'version_selector': bool,
99
    'language_selector': bool
100
}
101
```
102

103
[Theme Configuration](./theme-configuration.md)
104

105
### JavaScript Navigation API
106

107
Interactive navigation controller providing responsive behavior, mobile menu support, sticky navigation, and smooth scrolling with hash-based navigation state management.
108

109
```javascript { .api }
110
class ThemeNav {
111
    enable(withStickyNav?: boolean): void;
112
    enableSticky(): void;
113
    init($: jQuery): void;
114
    reset(): void;
115
    toggleCurrent(elem: jQuery): void;
116
}
117
```
118

119
[JavaScript Navigation](./javascript-navigation.md)
120

121
### Build System Integration
122

123
Asset compilation and translation management system with webpack integration, custom setup.py commands, and npm script integration for theme development and distribution.
124

125
```python { .api }
126
class WebpackBuildCommand: ...
127
class WebpackDevelopCommand: ...
128
class UpdateTranslationsCommand: ...
129
class TransifexCommand: ...
130
```
131

132
[Build System](./build-system.md)
133

134
## Package Metadata
135

136
```python { .api }
137
__version__ = "3.0.2"
138
__version_full__ = "3.0.2"
139
logger = getLogger(__name__)
140
```
141

142
## Dependencies
143

144
```python
145
# Required dependencies
146
sphinx >=6,<9
147
docutils >0.18,<0.22
148
sphinxcontrib-jquery >=4,<5
149

150
# Development dependencies
151
transifex-client
152
bump2version
153
wheel
154
twine
155
```
156

157
## Internationalization
158

159
Supports 21 languages with complete translation files:
160
- da, de, en, es, et, fa_IR, fr, hr, hu, it, lt, nl, pl, pt, pt_BR, ru, sv, tr, zh_CN, zh_TW