Skip to content

Commit a060931

Browse files
chrisjsewellchrisjsewell
committed
📚 DOCS: Improve tabs documentation
1 parent 423b8e2 commit a060931

File tree

14 files changed

+253
-17
lines changed

14 files changed

+253
-17
lines changed

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,9 @@ horizontal card (grid row inside card, picture on left)
7171
horizontally scrollable cards: (see <https://stackoverflow.com/questions/35993300/horizontally-scrollable-list-of-cards-in-bootstrap>)
7272

7373
div directive
74+
75+
subtitle for card (see <https://material.io/components/cards#anatomy>)
76+
77+
paragraph and tab-set in grid-item
78+
79+
finalise/document tab-set-code

‎docs/cards.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,16 @@
22

33
# Cards
44

5-
A card is a flexible and extensible content container.
6-
It can be formatted with components including headers and footers, titles and images.
5+
Cards contain content and actions about a single subject.
6+
A card is a flexible and extensible content container,
7+
it can be formatted with components including headers and footers, titles and images.
78

89
:::{card} Card Title
910

1011
Card content
1112
:::
1213

13-
See the [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) for further details.
14+
See the [Material Design](https://material.io/components/cards) and [Bootstrap card](https://getbootstrap.com/docs/5.0/layout/grid/) descriptions for further details.
1415

1516
`````{dropdown} Syntax
1617
:icon: code

‎docs/dropdowns.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
# Dropdowns
44

5-
Dropdowns can be used to hide, usually *non-essential*, content and show it only when a user clicks on the header panel.
5+
Dropdowns can be used to toggle, usually *non-essential*, content and show it only when a user clicks on the header panel.
6+
7+
The dropdown can have a title, as the directive argument, and the `open` option can be used to initialise the dropdown in the open state.
68

79
:::{dropdown}
810
Dropdown content
@@ -39,17 +41,13 @@ Use `:animate: fade-in` or `:animate: fade-in-slide-down` options to animate the
3941
:::{dropdown} Dropdown `fade-in`
4042
:animate: fade-in
4143

42-
Dropdown
43-
44-
content
44+
{{ loremipsum }}
4545
:::
4646

4747
:::{dropdown} Dropdown `fade-in-slide-down`
4848
:animate: fade-in-slide-down
4949

50-
Dropdown
51-
52-
content
50+
{{ loremipsum }}
5351
:::
5452

5553
## Dropdowns in other components

‎docs/snippets/myst/tab-basic.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
::::{tab-set}
2+
3+
:::{tab-item} Label1
4+
Content 1
5+
:::
6+
7+
:::{tab-item} Label2
8+
Content 2
9+
:::
10+
11+
::::

‎docs/snippets/myst/tab-sync.txt‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
::::{tab-set}
2+
3+
:::{tab-item} Label1
4+
:sync: key1
5+
6+
Content 1
7+
:::
8+
9+
:::{tab-item} Label2
10+
:sync: key2
11+
12+
Content 2
13+
:::
14+
15+
::::
16+
17+
::::{tab-set}
18+
19+
:::{tab-item} Label1
20+
:sync: key1
21+
22+
Content 1
23+
:::
24+
25+
:::{tab-item} Label2
26+
:sync: key2
27+
28+
Content 2
29+
:::
30+
31+
::::

‎docs/snippets/rst/tab-basic.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. tab-set::
2+
3+
.. tab-item:: Label1
4+
5+
Content 1
6+
7+
.. tab-item:: Label2
8+
9+
Content 2

‎docs/snippets/rst/tab-sync.txt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. tab-set::
2+
3+
.. tab-item:: Label1
4+
:sync: key1
5+
6+
Content 1
7+
8+
.. tab-item:: Label2
9+
:sync: key2
10+
11+
Content 2
12+
13+
.. tab-set::
14+
15+
.. tab-item:: Label1
16+
:sync: key1
17+
18+
Content 1
19+
20+
.. tab-item:: Label2
21+
:sync: key2
22+
23+
Content 2

‎docs/tabs.md‎

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
# Tabs
44

5+
Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.
6+
Each tab should contain content that is distinct from other tabs in a set.
7+
58
::::{tab-set}
69

710
:::{tab-item} Label1
@@ -14,18 +17,36 @@ Content 2
1417

1518
::::
1619

20+
`````{dropdown} Syntax
21+
:icon: code
22+
:color: light
23+
24+
````{tab-set-code}
25+
```{literalinclude} ./snippets/myst/tab-basic.txt
26+
:language: markdown
27+
```
28+
```{literalinclude} ./snippets/rst/tab-basic.txt
29+
:language: rst
30+
```
31+
````
32+
`````
33+
34+
See the [Material Design](https://material.io/components/tabs) description for further details.
35+
1736
## Synchronised Tabs
1837

38+
Use the `sync` option to synchronise the selected tab items across multiple tab-sets.
39+
1940
::::{tab-set}
2041

2142
:::{tab-item} Label1
22-
:sync: a
43+
:sync: key1
2344

2445
Content 1
2546
:::
2647

2748
:::{tab-item} Label2
28-
:sync: b
49+
:sync: key2
2950

3051
Content 2
3152
:::
@@ -35,21 +56,37 @@ Content 2
3556
::::{tab-set}
3657

3758
:::{tab-item} Label1
38-
:sync: a
59+
:sync: key1
3960

4061
Content 1
4162
:::
4263

4364
:::{tab-item} Label2
44-
:sync: b
65+
:sync: key2
4566

4667
Content 2
4768
:::
4869

4970
::::
5071

72+
`````{dropdown} Syntax
73+
:icon: code
74+
:color: light
75+
76+
````{tab-set-code}
77+
```{literalinclude} ./snippets/myst/tab-sync.txt
78+
:language: markdown
79+
```
80+
```{literalinclude} ./snippets/rst/tab-sync.txt
81+
:language: rst
82+
```
83+
````
84+
`````
85+
5186
## Tabs in other components
5287

88+
Tabs can be nested inside other components, such as inside [dropdowns](./dropdowns.md) or within [grid items](./grids.md).
89+
5390
:::::{dropdown} Tabs in dropdown
5491
:open:
5592

@@ -103,3 +140,23 @@ Content 2
103140
:::::
104141

105142
::::::
143+
144+
## `tab-item` options
145+
146+
selected
147+
: a flag indicating whether the tab should be selected by default.
148+
149+
sync
150+
: A key that is used to sync the selected tab across multiple tab-sets.
151+
152+
name
153+
: Set a reference-able name for the dropdown container.
154+
155+
class-container
156+
: Additional CSS classes for the container element.
157+
158+
class-label
159+
: Additional CSS classes for the label element.
160+
161+
class-content
162+
: Additional CSS classes for the content element.

‎sphinx_design/tabs.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ class TabItemDirective(SphinxDirective):
7676
"selected": directives.flag,
7777
"sync": directives.unchanged_required,
7878
"name": directives.unchanged,
79-
"class": directives.class_option,
79+
"class-container": directives.class_option,
8080
"class-label": directives.class_option,
8181
"class-content": directives.class_option,
8282
}
@@ -93,7 +93,7 @@ def run(self) -> List[nodes.Node]:
9393
)
9494
tab_item = create_component(
9595
"tab-item",
96-
classes=["sd-tab-item"] + self.options.get("class", []),
96+
classes=["sd-tab-item"] + self.options.get("class-container", []),
9797
selected=("selected" in self.options),
9898
)
9999

‎tests/conftest.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
from sphinx.testing.path import path as sphinx_path
88
from sphinx.testing.util import SphinxTestApp
99

10+
from sphinx_design.tabs import TabSetHtmlTransform
11+
1012
pytest_plugins = "sphinx.testing.fixtures"
1113

1214

@@ -58,7 +60,11 @@ def get_doctree(
5860

5961

6062
@pytest.fixture()
61-
def sphinx_builder(tmp_path: Path, make_app):
63+
def sphinx_builder(tmp_path: Path, make_app, monkeypatch):
64+
65+
# make sure tabbed id keys are reproducible across test runs
66+
monkeypatch.setattr(TabSetHtmlTransform, "get_unique_key", lambda self: "mock-uuid")
67+
6268
def _create_project(
6369
buildername: str = "html", conf_kwargs: Optional[Dict[str, Any]] = None
6470
):

0 commit comments

Comments
 (0)