0
# Sphinx Tabs
1

2
A Sphinx extension that enables developers to create tabbed content in HTML documentation. Sphinx Tabs provides multiple tab types including basic tabs, synchronized group tabs, and code tabs with syntax highlighting. The extension supports keyboard navigation, remembers tab selections across pages, and provides configuration options for various Sphinx builders.
3

4
## Package Information
5

6
- **Package Name**: sphinx-tabs
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install sphinx-tabs`
10

11
## Core Imports
12

13
Add the extension to your Sphinx configuration:
14

15
```python
16
# conf.py
17
extensions = ['sphinx_tabs.tabs']
18
```
19

20
## Basic Usage
21

22
```python
23
# conf.py - Basic setup
24
extensions = ['sphinx_tabs.tabs']
25

26
# Optional configuration
27
sphinx_tabs_valid_builders = ['linkcheck']  # Additional compatible builders
28
sphinx_tabs_disable_css_loading = False     # Use custom CSS
29
sphinx_tabs_disable_tab_closing = False     # Disable tab closing
30
```
31

32
Basic tabs in reStructuredText:
33

34
```rst
35
.. tabs::
36

37
   .. tab:: Python
38

39
      Python code example:
40

41
      .. code-block:: python
42

43
         def hello():
44
             print("Hello from Python!")
45

46
   .. tab:: JavaScript
47

48
      JavaScript code example:
49

50
      .. code-block:: javascript
51

52
         function hello() {
53
             console.log("Hello from JavaScript!");
54
         }
55
```
56

57
## Architecture
58

59
Sphinx Tabs uses a hierarchical structure of custom docutils nodes that render to accessible HTML:
60

61
- **Container Nodes**: `SphinxTabsContainer` wraps entire tab sets
62
- **Navigation**: `SphinxTabsTablist` contains clickable `SphinxTabsTab` buttons
63
- **Content**: `SphinxTabsPanel` contains the tab content
64
- **Directives**: RST directives (`tabs`, `tab`, `group-tab`, `code-tab`) generate the node structure
65
- **Assets**: Conditional loading of CSS/JS only on pages with tabs
66

67
The extension integrates with Sphinx's builder system and supports various output formats while maintaining ARIA accessibility standards.
68

69
## Capabilities
70

71
### Tab Directives
72

73
Core RST directives for creating different types of tabbed content including basic tabs, synchronized group tabs, and syntax-highlighted code tabs.
74

75
```python { .api }
76
# Directive registration in setup()
77
app.add_directive("tabs", TabsDirective)
78
app.add_directive("tab", TabDirective) 
79
app.add_directive("group-tab", GroupTabDirective)
80
app.add_directive("code-tab", CodeTabDirective)
81
```
82

83
[Tab Directives](./tab-directives.md)
84

85
### Configuration Options
86

87
Sphinx configuration values for customizing tab behavior, compatible builders, and asset loading.
88

89
```python { .api }
90
# Configuration values
91
sphinx_tabs_valid_builders = []      # List of additional compatible builders
92
sphinx_tabs_disable_css_loading = False  # Boolean to disable CSS loading
93
sphinx_tabs_disable_tab_closing = False  # Boolean to disable tab closing
94
```
95

96
[Configuration](./configuration.md)
97

98
### Extension Setup
99

100
Main extension setup function and compatibility detection for different Sphinx builders.
101

102
```python { .api }
103
def setup(app):
104
    """Set up the sphinx-tabs extension"""
105
    # Returns: dict with parallel processing settings
106

107
def get_compatible_builders(app):
108
    """Get list of builders compatible with sphinx-tabs"""
109
    # Returns: list of builder names
110
```
111

112
[Extension Setup](./extension-setup.md)