0
# Tab Directives
1

2
RST directives for creating different types of tabbed content in Sphinx documentation. All directives generate accessible HTML with ARIA attributes and support keyboard navigation.
3

4
## Capabilities
5

6
### Main Container Directive
7

8
Creates the top-level container for a set of tabs.
9

10
```python { .api }
11
class TabsDirective(SphinxDirective):
12
    """Top-level tabs directive"""
13
    has_content = True
14
    
15
    def run(self):
16
        """Parse a tabs directive and return container nodes"""
17
        # Returns: List[nodes.container]
18
```
19

20
**Usage:**
21
```rst
22
.. tabs::
23

24
   .. tab:: First Tab
25
   
26
      Content of first tab
27
      
28
   .. tab:: Second Tab
29
   
30
      Content of second tab
31
```
32

33
### Individual Tab Directive
34

35
Creates individual tabs within a tabs container.
36

37
```python { .api }
38
class TabDirective(SphinxDirective):
39
    """Tab directive for adding a tab to a collection"""
40
    has_content = True
41
    
42
    def run(self):
43
        """Parse a tab directive and return panel node"""
44
        # Returns: List[SphinxTabsPanel]
45
```
46

47
**Usage:**
48
```rst
49
.. tab:: Tab Title
50

51
   Any valid reStructuredText content can go here:
52
   
53
   - Lists
54
   - Code blocks
55
   - Images
56
   - Other directives
57
```
58

59
**Parameters:**
60
- First line becomes the tab title
61
- Remaining content becomes tab body
62
- Supports all standard RST content
63

64
### Group Tab Directive
65

66
Creates tabs that synchronize across multiple tab sets on the same page.
67

68
```python { .api }
69
class GroupTabDirective(TabDirective):
70
    """Tab directive that toggles with same tab names across page"""
71
    has_content = True
72
    
73
    def run(self):
74
        """Parse a group-tab directive with synchronization"""
75
        # Returns: List[SphinxTabsPanel] with group-tab class
76
```
77

78
**Usage:**
79
```rst
80
.. tabs::
81

82
   .. group-tab:: Linux
83
   
84
      Linux-specific instructions
85
      
86
   .. group-tab:: Windows
87
   
88
      Windows-specific instructions
89

90
.. tabs::
91

92
   .. group-tab:: Linux
93
   
94
      More Linux content (will sync with above)
95
      
96
   .. group-tab:: Windows
97
   
98
      More Windows content (will sync with above)
99
```
100

101
**Features:**
102
- Tabs with matching labels synchronize across tab sets
103
- Selection persists across page navigation (browser permitting)
104
- Base64 encoding used for internal tab IDs
105

106
### Code Tab Directive
107

108
Creates tabs with syntax-highlighted code blocks.
109

110
```python { .api }
111
class CodeTabDirective(GroupTabDirective):
112
    """Tab directive with a codeblock as its content"""
113
    has_content = True
114
    required_arguments = 1      # Lexer name
115
    optional_arguments = 1      # Custom label
116
    final_argument_whitespace = True
117
    
118
    # Inherits all CodeBlock options
119
    option_spec = {
120
        "force": directives.flag,
121
        "linenos": directives.flag,
122
        "dedent": int,
123
        "lineno-start": int,
124
        "emphasize-lines": directives.unchanged_required,
125
        "caption": directives.unchanged_required,
126
        "class": directives.class_option,
127
        "name": directives.unchanged,
128
    }
129
    
130
    def run(self):
131
        """Parse a code-tab directive with syntax highlighting"""
132
        # Returns: List[SphinxTabsPanel] with code content
133
```
134

135
**Usage:**
136
```rst
137
.. tabs::
138

139
   .. code-tab:: python
140

141
      def hello():
142
          print("Hello World!")
143

144
   .. code-tab:: javascript
145

146
      function hello() {
147
          console.log("Hello World!");
148
      }
149

150
   .. code-tab:: python Custom Label
151

152
      # Tab will show "Custom Label" instead of "Python"
153
      print("Custom labeled tab")
154
```
155

156
**Arguments:**
157
- **Required**: Lexer name (e.g., `python`, `javascript`, `c++`)
158
- **Optional**: Custom tab label (overrides language name)
159

160
**Options:**
161
- All Sphinx CodeBlock options supported:
162
  - `:linenos:` - Show line numbers
163
  - `:emphasize-lines: 1,3-5` - Highlight specific lines
164
  - `:caption: Code Example` - Add caption
165
  - `:dedent: 4` - Remove indentation
166
  - `:lineno-start: 10` - Start line numbering at 10
167

168
**Lexer Resolution:**
169
```python { .api }
170
# Internal lexer mapping
171
LEXER_MAP = {}  # Maps short names to full lexer names
172
# Populated from pygments.lexers.get_all_lexers()
173
```
174

175
**Error Handling:**
176
- Raises `ValueError` for unrecognized lexers
177
- Supports custom lexers added via Sphinx configuration
178
- Falls back to lexer name resolution through pygments
179

180
## HTML Output Structure
181

182
All directives generate the following HTML structure:
183

184
```html
185
<div class="sphinx-tabs">
186
  <div role="tablist" aria-label="Tabbed content">
187
    <button role="tab" id="tab-0-label" aria-selected="true" aria-controls="panel-0-label">
188
      Tab Label
189
    </button>
190
  </div>
191
  <div role="tabpanel" id="panel-0-label" aria-labelledby="tab-0-label">
192
    Tab content here
193
  </div>
194
</div>
195
```
196

197
## Accessibility Features
198

199
- Full ARIA support with proper roles and relationships
200
- Keyboard navigation (Tab, Arrow keys, Enter)
201
- Screen reader compatibility
202
- Focus management and visual indicators
203

204
## Browser Compatibility
205

206
- Modern browsers with JavaScript enabled
207
- Graceful degradation when JavaScript disabled
208
- Tab state persistence via localStorage (when supported)