Skip to content

Commit 0f3cbbe

Browse files
foster999foster999
authored
👌 IMPROVE: Add sphinx option to disable tab closing (#107)
1 parent 7632435 commit 0f3cbbe

22 files changed

+188
-64
lines changed

‎docs/index.rst‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,32 @@ To enable the extension in Sphinx, add the following to your conf.py:
1616
1717
extensions = ['sphinx_tabs.tabs']
1818
19-
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:
19+
If you are using `Read The Docs <https://readthedocs.org/>`_ for building your documentation, the extension must be added as a requirement. Please add `sphinx-tabs` to `requirements.txt` at the root of the project or in your docs folder.
20+
21+
Sphinx Configuration
22+
====================
23+
24+
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`:
2025

2126
.. code-block:: python
2227
2328
sphinx_tabs_valid_builders = ['linkcheck']
2429
25-
Custom lexers that have been loaded in the sphinx config can be used with `code-tabs`.
2630
27-
If you are using `Read The Docs <https://readthedocs.org/>`_ for building your documentation, the extension must be added as a requirement. Please add `sphinx-tabs` to `requirements.txt` at the root of the project.
31+
By default, tabs can be closed by selecting the open tab. This functionality can be disabled using the `sphinx_tabs_disable_tab_closing` configuration option:
32+
33+
.. code-block:: python
34+
35+
sphinx_tabs_disable_tab_closing = True
36+
37+
38+
Custom lexers that have been loaded in the sphinx `conf.py` can be used with `code-tabs`:
39+
40+
.. code-block:: python
41+
42+
def setup(app):
43+
app.add_lexer('alias', MyCustomLexer())
44+
2845
2946
Basic Tabs
3047
===========

‎sphinx_tabs/static/tabs.js‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ window.addEventListener("DOMContentLoaded", () => {
1616
tabList.addEventListener("keydown", keyTabs);
1717
});
1818

19+
// Restore group tab selection from session
1920
const lastSelected = session.getItem('sphinx-tabs-last-selected');
2021
if (lastSelected != null) selectGroupedTabs(lastSelected);
2122
});
@@ -59,10 +60,11 @@ function changeTabs(e) {
5960
// Use this instead of the element that was clicked, in case it's a child
6061
const selected = this.getAttribute("aria-selected") === "true";
6162
const positionBefore = this.parentNode.getBoundingClientRect().top;
63+
const closable = this.parentNode.classList.contains("closeable");
6264

63-
deselectTabset(this);
65+
deselectTabList(this);
6466

65-
if (!selected) {
67+
if (!selected || !closable) {
6668
selectTab(this);
6769
const name = this.getAttribute("name");
6870
selectGroupedTabs(name, this.id);
@@ -88,6 +90,11 @@ function selectTab(target) {
8890
.removeAttribute("hidden");
8991
}
9092

93+
/**
94+
* Select all other grouped tabs via tab name.
95+
* @param {Node} name name of grouped tab to be selected
96+
* @param {Node} clickedId id of clicked tab
97+
*/
9198
function selectGroupedTabs(name, clickedId=null) {
9299
const groupedTabs = document.querySelectorAll(`.sphinx-tabs-tab[name="${name}"]`);
93100
const tabLists = Array.from(groupedTabs).map(tab => tab.parentNode);
@@ -99,21 +106,24 @@ function selectGroupedTabs(name, clickedId=null) {
99106
if (clickedTab === null ) {
100107
// Select first tab with matching name
101108
const tab = tabList.querySelector(`.sphinx-tabs-tab[name="${name}"]`);
102-
deselectTabset(tab);
109+
deselectTabList(tab);
103110
selectTab(tab);
104111
}
105112
})
106113
}
107114

108-
function deselectTabset(target) {
109-
const parent = target.parentNode;
115+
/**
116+
* Hide the panels associated with all tabs within the
117+
* tablist containing this tab.
118+
* @param {Node} tab a tab within the tablist to deselect
119+
*/
120+
function deselectTabList(tab) {
121+
const parent = tab.parentNode;
110122
const grandparent = parent.parentNode;
111123

112-
// Hide all tabs in current tablist, but not nested
113124
Array.from(parent.children)
114125
.forEach(t => t.setAttribute("aria-selected", false));
115126

116-
// Hide all associated panels
117127
Array.from(grandparent.children)
118128
.slice(1) // Skip tablist
119129
.forEach(p => p.setAttribute("hidden", true));

‎sphinx_tabs/tabs.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,8 @@ def run(self):
104104
tablist = SphinxTabsTablist()
105105
tablist["role"] = "tablist"
106106
tablist["aria-label"] = "Tabbed content"
107+
if not self.env.config["sphinx_tabs_disable_tab_closing"]:
108+
tablist["classes"].append("closeable")
107109

108110
tab_titles = self.env.temp_data[tabs_key]["tab_titles"]
109111
for idx, [data_tab, tab_name] in enumerate(tab_titles):
@@ -316,6 +318,7 @@ def update_context(app, pagename, templatename, context, doctree):
316318
def setup(app):
317319
""" Set up the plugin """
318320
app.add_config_value("sphinx_tabs_valid_builders", [], "")
321+
app.add_config_value("sphinx_tabs_disable_tab_closing", False, "html", [bool])
319322
app.add_node(SphinxTabsContainer, html=(visit, depart))
320323
app.add_node(SphinxTabsPanel, html=(visit, depart))
321324
app.add_node(SphinxTabsTab, html=(visit, depart))

‎tests/roots/test-disable-closing/conf.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
project = "sphinx-tabs test"
2+
master_doc = "index"
3+
source_suffix = ".rst"
4+
extensions = ["sphinx_tabs.tabs"]
5+
pygments_style = "sphinx"
6+
7+
sphinx_tabs_disable_tab_closing = True

‎tests/roots/test-disable-closing/index.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. tabs::
2+
3+
.. tab:: Apples
4+
5+
Apples are green, or sometimes red.
6+
7+
.. tab:: Pears
8+
9+
Pears are green.
10+
11+
.. tab:: Oranges
12+
13+
Oranges are orange.
14+
15+
.. tab:: 404
16+
17+
A number in the name.

‎tests/test_build.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,8 @@ def test_rinohtype_pdf(
4545
check_build_success(status, warning)
4646
get_sphinx_app_doctree(app, regress=True)
4747
# Doesn't currently regression pdf test output
48+
49+
50+
@pytest.mark.sphinx(testroot="disable-closing")
51+
def test_disable_closing(app, check_asset_links):
52+
check_asset_links(app)

‎tests/test_build/test_basic.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<div class="bodywrapper">
33
<div class="body" role="main">
44
<div class="sphinx-tabs docutils container">
5-
<div aria-label="Tabbed content" role="tablist">
5+
<div aria-label="Tabbed content" class="closeable" role="tablist">
66
<button aria-controls="panel-0-0-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-0-0-0" name="0-0" role="tab" tabindex="0">
77
Apples
88
</button>

‎tests/test_build/test_basic.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<document source="index.rst">
22
<container classes="sphinx-tabs" type="tab-element">
3-
<div aria-label="Tabbed content" role="tablist">
3+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
44
<button aria-controls="panel-0-0-0" aria-selected="true" classes="sphinx-tabs-tab" ids="tab-0-0-0" name="0-0" role="tab" tabindex="0">
55
Apples
66
<button aria-controls="panel-0-0-1" aria-selected="false" classes="sphinx-tabs-tab" ids="tab-0-0-1" name="0-1" role="tab" tabindex="-1">

‎tests/test_build/test_conditional_assets_index_.html‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ <h1>
2323
</a>
2424
</h1>
2525
<div class="sphinx-tabs docutils container">
26-
<div aria-label="Tabbed content" role="tablist">
26+
<div aria-label="Tabbed content" class="closeable" role="tablist">
2727
<button aria-controls="panel-0-0-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-0-0-0" name="0-0" role="tab" tabindex="0">
2828
Apples
2929
</button>
@@ -59,7 +59,7 @@ <h1>
5959
</a>
6060
</h1>
6161
<div class="sphinx-tabs docutils container">
62-
<div aria-label="Tabbed content" role="tablist">
62+
<div aria-label="Tabbed content" class="closeable" role="tablist">
6363
<button aria-controls="panel-1-1-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-1-1-0" name="1-0" role="tab" tabindex="0">
6464
Sun
6565
</button>
@@ -87,7 +87,7 @@ <h1>
8787
</a>
8888
</h1>
8989
<div class="sphinx-tabs docutils container">
90-
<div aria-label="Tabbed content" role="tablist">
90+
<div aria-label="Tabbed content" class="closeable" role="tablist">
9191
<button aria-controls="panel-2-Qw==" aria-selected="true" class="sphinx-tabs-tab code-tab group-tab" id="tab-2-Qw==" name="Qw==" role="tab" tabindex="0">
9292
C
9393
</button>
@@ -157,7 +157,7 @@ <h1>
157157
</div>
158158
</div>
159159
<div class="sphinx-tabs docutils container">
160-
<div aria-label="Tabbed content" role="tablist">
160+
<div aria-label="Tabbed content" class="closeable" role="tablist">
161161
<button aria-controls="panel-3-Qw==" aria-selected="true" class="sphinx-tabs-tab code-tab group-tab" id="tab-3-Qw==" name="Qw==" role="tab" tabindex="0">
162162
C
163163
</button>
@@ -245,7 +245,7 @@ <h1>
245245
</a>
246246
</h1>
247247
<div class="sphinx-tabs docutils container">
248-
<div aria-label="Tabbed content" role="tablist">
248+
<div aria-label="Tabbed content" class="closeable" role="tablist">
249249
<button aria-controls="panel-4-TGludXg=" aria-selected="true" class="sphinx-tabs-tab group-tab" id="tab-4-TGludXg=" name="TGludXg=" role="tab" tabindex="0">
250250
Linux
251251
</button>
@@ -273,7 +273,7 @@ <h1>
273273
</div>
274274
</div>
275275
<div class="sphinx-tabs docutils container">
276-
<div aria-label="Tabbed content" role="tablist">
276+
<div aria-label="Tabbed content" class="closeable" role="tablist">
277277
<button aria-controls="panel-5-TGludXg=" aria-selected="true" class="sphinx-tabs-tab group-tab" id="tab-5-TGludXg=" name="TGludXg=" role="tab" tabindex="0">
278278
Linux
279279
</button>

‎tests/test_build/test_conditional_assets_index_.xml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<title>
66
Fruits
77
<container classes="sphinx-tabs" type="tab-element">
8-
<div aria-label="Tabbed content" role="tablist">
8+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
99
<button aria-controls="panel-0-0-0" aria-selected="true" classes="sphinx-tabs-tab" ids="tab-0-0-0" name="0-0" role="tab" tabindex="0">
1010
Apples
1111
<button aria-controls="panel-0-0-1" aria-selected="false" classes="sphinx-tabs-tab" ids="tab-0-0-1" name="0-1" role="tab" tabindex="-1">
@@ -25,7 +25,7 @@
2525
<title>
2626
Luminaries
2727
<container classes="sphinx-tabs" type="tab-element">
28-
<div aria-label="Tabbed content" role="tablist">
28+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
2929
<button aria-controls="panel-1-1-0" aria-selected="true" classes="sphinx-tabs-tab" ids="tab-1-1-0" name="1-0" role="tab" tabindex="0">
3030
Sun
3131
<button aria-controls="panel-1-1-1" aria-selected="false" classes="sphinx-tabs-tab" ids="tab-1-1-1" name="1-1" role="tab" tabindex="-1">
@@ -40,7 +40,7 @@
4040
<title>
4141
Code Tabs
4242
<container classes="sphinx-tabs" type="tab-element">
43-
<div aria-label="Tabbed content" role="tablist">
43+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
4444
<button aria-controls="panel-2-Qw==" aria-selected="true" classes="sphinx-tabs-tab code-tab group-tab" ids="tab-2-Qw==" name="Qw==" role="tab" tabindex="0">
4545
C
4646
<button aria-controls="panel-2-Qysr" aria-selected="false" classes="sphinx-tabs-tab code-tab group-tab" ids="tab-2-Qysr" name="Qysr" role="tab" tabindex="-1">
@@ -72,7 +72,7 @@
7272
<literal_block force="False" highlight_args="{}" language="fortran" xml:space="preserve">
7373
Fortran Main Function
7474
<container classes="sphinx-tabs" type="tab-element">
75-
<div aria-label="Tabbed content" role="tablist">
75+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
7676
<button aria-controls="panel-3-Qw==" aria-selected="true" classes="sphinx-tabs-tab code-tab group-tab" ids="tab-3-Qw==" name="Qw==" role="tab" tabindex="0">
7777
C
7878
<button aria-controls="panel-3-Qysr" aria-selected="false" classes="sphinx-tabs-tab code-tab group-tab" ids="tab-3-Qysr" name="Qysr" role="tab" tabindex="-1">
@@ -117,7 +117,7 @@
117117
<title>
118118
Group Tabs
119119
<container classes="sphinx-tabs" type="tab-element">
120-
<div aria-label="Tabbed content" role="tablist">
120+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
121121
<button aria-controls="panel-4-TGludXg=" aria-selected="true" classes="sphinx-tabs-tab group-tab" ids="tab-4-TGludXg=" name="TGludXg=" role="tab" tabindex="0">
122122
Linux
123123
<button aria-controls="panel-4-TWFjIE9TWA==" aria-selected="false" classes="sphinx-tabs-tab group-tab" ids="tab-4-TWFjIE9TWA==" name="TWFjIE9TWA==" role="tab" tabindex="-1">
@@ -134,7 +134,7 @@
134134
<paragraph>
135135
Windows Line 1
136136
<container classes="sphinx-tabs" type="tab-element">
137-
<div aria-label="Tabbed content" role="tablist">
137+
<div aria-label="Tabbed content" classes="closeable" role="tablist">
138138
<button aria-controls="panel-5-TGludXg=" aria-selected="true" classes="sphinx-tabs-tab group-tab" ids="tab-5-TGludXg=" name="TGludXg=" role="tab" tabindex="0">
139139
Linux
140140
<button aria-controls="panel-5-TWFjIE9TWA==" aria-selected="false" classes="sphinx-tabs-tab group-tab" ids="tab-5-TWFjIE9TWA==" name="TWFjIE9TWA==" role="tab" tabindex="-1">

0 commit comments

Comments
 (0)