1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# sphinx-tabs
[![Github-CI][github-ci]][github-link]
[![Coverage Status][codecov-badge]][codecov-link]
[![PyPI][pypi-badge]][pypi-link]
Create tabbed content in [Sphinx documentation](http://www.sphinx-doc.org) when building HTML.
For example, see the [Raw] code of [docs/index.rst](docs/index.rst) which generates the following:
A live demo can be found here: <https://sphinx-tabs.readthedocs.io>
## Installation
```bash
pip install sphinx-tabs
```
To enable the extension in Sphinx, add the following to your conf.py:
```python
extensions = ['sphinx_tabs.tabs']
```
If needed, there is a configuration option to allow additional builders to be considered compatible. For example, to add the `linkcheck` builder, add the following to your conf.py:
```python
sphinx_tabs_valid_builders = ['linkcheck']
```
If you are using [Read The Docs](https://readthedocs.org/) for building your documentation, the extension must be added as a requirement. Please add the following to `requirements.txt` at the root of the project:
```
sphinx-tabs
```
## Contributing
We welcome all contributions!
See the [EBP Contributing Guide](https://executablebooks.org/en/latest/contributing.html) for general details.
The simplest way to run tests is to install [pre-commit](https://pre-commit.com/) for linting and [tox](https://tox.readthedocs.io) for unit tests and documentation build:
```console
$ pre-commit run --all
```
```console
$ tox -p
```
## Basic Tabs
Basic tabs can be coded as follows:
```rst
.. tabs::
.. tab:: Apples
Apples are green, or sometimes red.
.. tab:: Pears
Pears are green.
.. tab:: Oranges
Oranges are orange.
```
The contents of each tab can be displayed by clicking on the tab that you wish to show. Clicking on the tab that is currently open will hide the tab's content, leaving only the tab set labels visible.
Alternatively, tab sets can be focused using :kbd:`Tab`. The :kbd:`Left Arrow` and :kbd:`Right Arrow` keys can then be used to navigate across the tab set and :kbd:`Enter` can be used to select a tab.
## Grouped Tabs
Tabs can be grouped, so that changing the current tab in one tabset changes the current tab in all other tabsets containing a tab with a matching label.
For example:
```rst
.. tabs::
.. group-tab:: Linux
Linux Line 1
.. group-tab:: Mac OSX
Mac OSX Line 1
.. group-tab:: Windows
Windows Line 1
.. tabs::
.. group-tab:: Linux
Linux Line 1
.. group-tab:: Mac OSX
Mac OSX Line 1
.. group-tab:: Windows
Windows Line 1
```
If permitted by the user's browser, the last selected group tab will be remembered when changing page. As such, if any tabsets on the next page contain a tab with the same label it will be selected.
## Code Tabs
Grouped tabs containing code with syntax highlighting can be created as follows:
```rst
.. tabs::
.. code-tab:: c
int main(const int argc, const char **argv) {
return 0;
}
.. code-tab:: c++
int main(const int argc, const char **argv) {
return 0;
}
.. code-tab:: py
def main():
return
.. code-tab:: java
class Main {
public static void main(String[] args) {
}
}
.. code-tab:: julia
function main()
end
.. code-tab:: fortran
PROGRAM main
END PROGRAM main
```
Code tabs also support custom lexers (added via sphinx `conf.py`). Pass the lexers alias as the first argument of `code-tab`.
By default, code tabs are labelled with the language name, though a custom label can be provided as an optional second argument to the `code-tabs` directive:
```rst
.. tabs::
.. code-tab:: c I love C
int main(const int argc, const char **argv) {
return 0;
}
.. code-tab:: py I love Python more
def main():
return
```
The tab label is used to group tabs, including `code-tabs`. As such, the same custom label should be used to group related tabs.
[github-ci]: https://github.com/executablebooks/sphinx-tabs/workflows/continuous-integration/badge.svg?branch=master
[github-link]: https://github.com/executablebooks/sphinx-tabs
[pypi-badge]: https://img.shields.io/pypi/v/sphinx-tabs.svg
[pypi-link]: https://pypi.org/project/sphinx-tabs
[codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-tabs/branch/master/graph/badge.svg
[codecov-link]: https://codecov.io/gh/executablebooks/sphinx-tabs
|
