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
|
sphinx code tabs
================
|Version| |License| |Documentation|
This is a Sphinx extension that adds a ``tabs`` directive for creating a
tabbed widget, allowing the user to switch between them. The individual tabs
can be code blocks or general content.
This can be used to e.g. show a snippet in multiple languages, display
instructions for alternative platforms, or switch between code and output.
|Screenshot|
Installation
------------
.. code-block:: bash
pip install sphinx_code_tabs
To enable the extension in sphinx, simply add the package name in your
``conf.py`` to the list of ``extensions``:
.. code-block:: python
extensions = [
...
'sphinx_code_tabs',
]
Usage
-----
By enabling the extension you get access to the ``tabs`` directive that
declares a notebook of code block alternatives.
The individual tabs are created with the ``tab`` or ``code-tab`` directives. A
``tab`` can contain arbitrary restructuredText, while a ``code-tab`` acts like
a ``code-block`` and accepts all corresponding arguments. Both types of tabs
can appear in the same notebook.
The ``:selected:`` option allows to switch to a specified tab at start. By
default, the first tab is used.
For example, this is the source of above example:
.. code-block:: rst
.. tabs::
.. code-tab:: bash
echo "Hello, *World*!"
.. code-tab:: c
:caption: C/C++
:emphasize-lines: 2
#include <stdio.h>
int main() { printf("Hello, *World*!\n"); }
.. code-tab:: python
print("Hello, *World*!")
.. tab:: Output
:selected:
Hello, *World*!
Grouped tabs
~~~~~~~~~~~~
The ``tabs`` directive takes an optional argument that identifies its *tab
group*. Within a given tab group, all notebooks will automatically be switched
to the same tab number if the tab is switched in one member of the group.
It is your responsibility to make sure that each member of the group has the
same number and ordering of tabs. Example:
|Tabgroup|
Source:
.. code-block:: rst
.. tabs:: lang
.. code-tab:: bash
echo "Hello, group!"
.. code-tab:: python
print("Hello, group!")
.. tabs:: lang
.. code-tab:: bash
echo "Goodbye, group!"
.. code-tab:: python
print("Goodbye, group!")
Alternatives
------------
After creating this package, I found other packages which are functionally
similar or equivalent. You may want to check them out if sphinx-code-tabs
doesn't fit your needs:
- sphinx_tabs_
- sphinx_inline_tabs_
.. _sphinx_tabs: https://pypi.org/project/sphinx-tabs/
.. _sphinx_inline_tabs: https://pypi.org/project/sphinx-inline-tabs/
.. |Documentation| image:: https://readthedocs.org/projects/sphinx-code-tabs/badge/?version=latest
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/
:alt: Documentation
.. |License| image:: https://img.shields.io/pypi/l/sphinx-code-tabs.svg
:target: https://github.com/coldfix/sphinx-code-tabs/blob/main/UNLICENSE
:alt: License: Unlicense
.. |Version| image:: https://img.shields.io/pypi/v/sphinx-code-tabs.svg
:target: https://pypi.org/project/sphinx-code-tabs
:alt: Latest Version
.. |Screenshot| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot1.webp
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/#usage
:alt: Code tabs screenshot
.. |Tabgroup| image:: https://raw.githubusercontent.com/coldfix/sphinx-code-tabs/main/screenshot2.webp
:target: https://sphinx-code-tabs.readthedocs.io/en/latest/#grouped-tabs
:alt: Grouped tabs screenshot
|
