Skip to content

Commit 423b8e2

Browse files
chrisjsewellchrisjsewell
committed
📚 DOCS: Improve dropdown documentation
1 parent 37ab742 commit 423b8e2

File tree

8 files changed

+184
-16
lines changed

8 files changed

+184
-16
lines changed

‎README.md‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ This package is an iteration on sphinx-panels and intends to replace it.
4848

4949
## TODO
5050

51+
- note design goal; to be flexible, but limit the amount of directive nesting required.
52+
This factors in to
53+
- card header/footer syntax? (don't really want to have to use separate directives for these, hence `^^^`/`+++` syntax)
54+
- auto-wrap `grid-item` and `tab-item`, if not already inside `grid` or `tab-set`?
55+
5156
note that directly using classes should be used as a "last resort",
5257
and to please open an issue if you find you are commonly using a certain class.
5358

@@ -57,20 +62,12 @@ naming of directives/roles: standard prefix?
5762

5863
why are cards setup with "word-wrap: break-word;"?
5964

60-
check grid-items and tab-items are inside parents (or auto-wrap?)
61-
6265
handle latex
6366

64-
card header/footer syntax?
65-
6667
Use autoprefixer when compiling SASS (see <https://getbootstrap.com/docs/5.0/getting-started/browsers-devices/#supported-browsers>)
6768

6869
horizontal card (grid row inside card, picture on left)
6970

7071
horizontally scrollable cards: (see <https://stackoverflow.com/questions/35993300/horizontally-scrollable-list-of-cards-in-bootstrap>)
7172

72-
from inline-tabs:
73-
74-
- **Elegant design**: Small footprint in the markup and generated website, while looking good.
75-
- **Configurable**: All the colors can be configured using CSS variables.
76-
- **Works without JavaScript**: JavaScript is not required for "essential" functionality, only for tab synchronisation.
73+
div directive

‎docs/cards.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ The entire card can be clicked to navigate to the `cards-clickable` reference ta
123123

124124
## Aligning cards
125125

126+
You can use the `text-align` option to align the text in a card,
127+
and also `auto` margins to align the cards horizontally.
128+
126129
:::{card} Align Center
127130
:width: 75%
128131
:margin: 0 2 auto auto

‎docs/dropdowns.md‎

Lines changed: 81 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,61 @@
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.
6+
7+
:::{dropdown}
8+
Dropdown content
9+
:::
10+
511
:::{dropdown} Dropdown title
612
Dropdown content
713
:::
814

9-
:::{dropdown}
15+
:::{dropdown} Open dropdown
16+
:open:
17+
1018
Dropdown content
1119
:::
1220

13-
::::{dropdown} Parent dropdown title (open by default)
21+
`````{dropdown} Syntax
22+
:icon: code
23+
:color: light
24+
25+
````{tab-set-code}
26+
```{literalinclude} ./snippets/myst/dropdown-basic.txt
27+
:language: markdown
28+
```
29+
```{literalinclude} ./snippets/rst/dropdown-basic.txt
30+
:language: rst
31+
```
32+
````
33+
`````
34+
35+
## Dropdown opening animations
36+
37+
Use `:animate: fade-in` or `:animate: fade-in-slide-down` options to animate the reveal of the hidden content.
38+
39+
:::{dropdown} Dropdown `fade-in`
40+
:animate: fade-in
41+
42+
Dropdown
43+
44+
content
45+
:::
46+
47+
:::{dropdown} Dropdown `fade-in-slide-down`
48+
:animate: fade-in-slide-down
49+
50+
Dropdown
51+
52+
content
53+
:::
54+
55+
## Dropdowns in other components
56+
57+
Dropdowns can be nested inside other components, such as inside parent dropdowns or within [grid items](./grids.md).
58+
59+
::::{dropdown} Parent dropdown title
1460
:open:
1561

1662
:::{dropdown} Child dropdown title
@@ -21,21 +67,50 @@ Dropdown content
2167
:::
2268
::::
2369

24-
## Dropdowns in a grid
25-
2670
:::::{grid} 1 1 2 2
2771
:gutter: 1
2872

2973
::::{grid-item}
30-
:::{dropdown} Dropdown title
74+
:::{dropdown} Dropdown Column 1
3175
Dropdown content
3276
:::
3377
::::
3478

3579
::::{grid-item}
36-
:::{dropdown} Dropdown title
80+
:::{dropdown} Dropdown Column 2
3781
Dropdown content
3882
:::
3983
::::
4084

4185
:::::
86+
87+
## `dropdown` options
88+
89+
open
90+
: Open the dropdown by default.
91+
92+
color
93+
: Set the color of the dropdown header (background and font).
94+
One of the semantic color names: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `muted`.
95+
96+
icon
97+
: Set an [octicon icon](icons) to prefix the dropdown header.
98+
99+
animate
100+
: Animate the dropdown opening (`fade-in` or `fade-in-slide-down`).
101+
102+
margin
103+
: Outer margin of grid.
104+
One (all) or four (top bottom left right) values from: 0, 1, 2, 3, 4, 5, auto.
105+
106+
name
107+
: Set a reference-able name for the dropdown container.
108+
109+
class-container
110+
: Additional CSS classes for the container element.
111+
112+
class-title
113+
: Additional CSS classes for the title element.
114+
115+
class-body
116+
: Additional CSS classes for the body element.

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:::{dropdown}
2+
Dropdown content
3+
:::
4+
5+
:::{dropdown} Dropdown title
6+
Dropdown content
7+
:::
8+
9+
:::{dropdown} Open dropdown
10+
:open:
11+
12+
Dropdown content
13+
:::

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. dropdown::
2+
3+
Dropdown content
4+
5+
.. dropdown:: Dropdown title
6+
7+
Dropdown content
8+
9+
.. dropdown:: Open dropdown
10+
:open:
11+
12+
Dropdown content

‎sphinx_design/dropdown.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
create_component,
1212
is_component,
1313
make_choice,
14+
margin_option,
1415
)
1516

1617
from .icons import get_octicon, list_octicons
@@ -75,6 +76,7 @@ class DropdownDirective(SphinxDirective):
7576
"color": make_choice(SEMANTIC_COLORS),
7677
"icon": make_choice(list_octicons()),
7778
"animate": make_choice(("fade-in", "fade-in-slide-down")),
79+
"margin": margin_option,
7880
"name": directives.unchanged,
7981
"class-container": directives.class_option,
8082
"class-title": directives.class_option,
@@ -85,7 +87,8 @@ def run(self):
8587
"""Run the directive"""
8688
# default classes
8789
classes = {
88-
"container_classes": self.options.get("class-container", ["sd-mb-3"]),
90+
"container_classes": self.options.get("margin", ["sd-mb-3"])
91+
+ self.options.get("class-container", []),
8992
"title_classes": self.options.get("class-title", []),
9093
"body_classes": self.options.get("class-body", []),
9194
}

‎tests/test_snippets/snippet_post_dropdown-basic.xml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<document source="index">
2+
<section ids="heading" names="heading">
3+
<title>
4+
Heading
5+
<dropdown_main classes="sd-sphinx-override sd-dropdown sd-card sd-mb-3" opened="False">
6+
<dropdown_title classes="sd-summary-title sd-card-header">
7+
<raw format="html" xml:space="preserve">
8+
<svg viewBox="0 0 36 24" width="36" height="16" xmlns="http://www.w3.org/2000/svg"
9+
class="octicon no-title" aria-hidden="true">
10+
<g xmlns="http://www.w3.org/2000/svg" class="jp-icon3">
11+
<circle cx="0" cy="12" r="6"></circle>
12+
<circle cx="18" cy="12" r="6"></circle>
13+
<circle cx="36" cy="12" r="6"></circle>
14+
</g>
15+
</svg>
16+
<container classes="sd-summary-down" design_component="dropdown-closed-marker" is_div="True">
17+
<raw format="html" xml:space="preserve">
18+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-down" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M5.22 8.72a.75.75 0 000 1.06l6.25 6.25a.75.75 0 001.06 0l6.25-6.25a.75.75 0 00-1.06-1.06L12 14.44 6.28 8.72a.75.75 0 00-1.06 0z"></path></svg>
19+
<container classes="sd-summary-up" design_component="dropdown-open-marker" is_div="True">
20+
<raw format="html" xml:space="preserve">
21+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-up" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M18.78 15.28a.75.75 0 000-1.06l-6.25-6.25a.75.75 0 00-1.06 0l-6.25 6.25a.75.75 0 101.06 1.06L12 9.56l5.72 5.72a.75.75 0 001.06 0z"></path></svg>
22+
<container classes="sd-summary-content sd-card-body" design_component="dropdown-body" is_div="True">
23+
<paragraph classes="sd-card-text">
24+
Dropdown content
25+
<dropdown_main classes="sd-sphinx-override sd-dropdown sd-card sd-mb-3" opened="False">
26+
<dropdown_title classes="sd-summary-title sd-card-header">
27+
Dropdown title
28+
<container classes="sd-summary-down" design_component="dropdown-closed-marker" is_div="True">
29+
<raw format="html" xml:space="preserve">
30+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-down" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M5.22 8.72a.75.75 0 000 1.06l6.25 6.25a.75.75 0 001.06 0l6.25-6.25a.75.75 0 00-1.06-1.06L12 14.44 6.28 8.72a.75.75 0 00-1.06 0z"></path></svg>
31+
<container classes="sd-summary-up" design_component="dropdown-open-marker" is_div="True">
32+
<raw format="html" xml:space="preserve">
33+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-up" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M18.78 15.28a.75.75 0 000-1.06l-6.25-6.25a.75.75 0 00-1.06 0l-6.25 6.25a.75.75 0 101.06 1.06L12 9.56l5.72 5.72a.75.75 0 001.06 0z"></path></svg>
34+
<container classes="sd-summary-content sd-card-body" design_component="dropdown-body" is_div="True">
35+
<paragraph classes="sd-card-text">
36+
Dropdown content
37+
<dropdown_main classes="sd-sphinx-override sd-dropdown sd-card sd-mb-3" opened="True">
38+
<dropdown_title classes="sd-summary-title sd-card-header">
39+
Open dropdown
40+
<container classes="sd-summary-down" design_component="dropdown-closed-marker" is_div="True">
41+
<raw format="html" xml:space="preserve">
42+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-down" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M5.22 8.72a.75.75 0 000 1.06l6.25 6.25a.75.75 0 001.06 0l6.25-6.25a.75.75 0 00-1.06-1.06L12 14.44 6.28 8.72a.75.75 0 00-1.06 0z"></path></svg>
43+
<container classes="sd-summary-up" design_component="dropdown-open-marker" is_div="True">
44+
<raw format="html" xml:space="preserve">
45+
<svg version="1.1" width="24" height="24" class="sd-octicon sd-octicon-chevron-up" viewBox="0 0 24 24" aria-hidden="true"><path fill-rule="evenodd" d="M18.78 15.28a.75.75 0 000-1.06l-6.25-6.25a.75.75 0 00-1.06 0l-6.25 6.25a.75.75 0 101.06 1.06L12 9.56l5.72 5.72a.75.75 0 001.06 0z"></path></svg>
46+
<container classes="sd-summary-content sd-card-body" design_component="dropdown-body" is_div="True">
47+
<paragraph classes="sd-card-text">
48+
Dropdown content

‎tests/test_snippets/snippet_pre_dropdown-basic.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<document source="index">
2+
<section ids="heading" names="heading">
3+
<title>
4+
Heading
5+
<container body_classes="" container_classes="sd-mb-3" design_component="dropdown" has_title="False" icon="True" is_div="True" opened="False" title_classes="" type="dropdown">
6+
<paragraph>
7+
Dropdown content
8+
<container body_classes="" container_classes="sd-mb-3" design_component="dropdown" has_title="True" icon="True" is_div="True" opened="False" title_classes="" type="dropdown">
9+
<rubric>
10+
Dropdown title
11+
<paragraph>
12+
Dropdown content
13+
<container body_classes="" container_classes="sd-mb-3" design_component="dropdown" has_title="True" icon="True" is_div="True" opened="True" title_classes="" type="dropdown">
14+
<rubric>
15+
Open dropdown
16+
<paragraph>
17+
Dropdown content

0 commit comments

Comments
 (0)